Flow Metadata And Discover

Reference for mutable flow metadata managed around a workspace flow record.

Quick Answer

Use this page when you are managing grouped flows, display-icon selection,
discover card media, install-surface copy, marketplace visibility, paid
monetization, or public discover visibility.

These settings live on the workspace flow record. Some can also be authored in
the flow source and persisted on push.

Metadata Vs Source

breyta flows show, breyta flows pull, and breyta flows validate target
draft by default.
Grouping metadata is mutable workspace metadata, not part of the pulled flow
source file.
Marketplace visibility is stored metadata. It can also be authored in the
flow file with :marketplace {:visible true} and then persisted on push.
Paid app monetization is stored metadata. For new source-authored paid apps,
put the catalog under :marketplace {:app {... :monetization {:plans [...]}}}
and persist it with breyta flows push.
Legacy flow-level monetization under :marketplace {:monetization {...}}
remains supported for existing listings, but new paid apps should use the
app-owned shape so Discover, checkout, billing, and install ownership share
the same app and plan identity.
Display-icon selection is mutable workspace metadata, not part of the pulled
flow source file.
Publish description is mutable workspace metadata, not part of the pulled
flow source file.
Discover card media is stored metadata. It can also be authored in the flow
file with :publish-media and then persisted on push.
Public discover visibility is stored metadata. It can also be authored in the
flow file with :discover {:public true} and then persisted on push.

Grouping Metadata

Use breyta flows update to manage grouped-flow metadata:

breyta flows update billing-sync \
  --group-key billing \
  --group-name "Billing" \
  --group-description "Billing operations" \
  --group-order 20

Inspect stored grouping state with:

breyta flows list --pretty
breyta flows show billing-sync --pretty

Grouped-flow responses expose fields such as:

groupKey
groupName
groupDescription
groupOrder
groupFlows on flows show --pretty

Clear only ordering:

breyta flows update billing-sync --group-order ""

Clear the full group:

breyta flows update billing-sync --group-key ""

Display Icon Selection

Use --primary-display-connection-slot to choose which connection/provider
icon renders anywhere the flow icon is shown:

breyta flows update billing-sync \
  --primary-display-connection-slot crm

Selectors can come from declared :requires slots or normalized keys from
:connections.
JSON responses may include _hints that help inspect candidate selectors.
If unset or no longer matched, rendering falls back to the first explicit
:connections icon, then the first inferred :requires icon.

Clear the selector with:

breyta flows update billing-sync --primary-display-connection-slot ""

Marketplace Visibility

Use marketplace visibility when the flow should be shown as a marketplace item
in discover/install surfaces:

breyta flows marketplace update billing-sync --visible=true

Notes:

This is separate from discover.public.
The public marketing app page for a visible marketplace flow is
https://breyta.ai/apps/<flow-slug>.
You can also author the same value in source as :marketplace {:visible true}
and persist it with breyta flows push.
Use breyta flows show billing-sync --pretty to confirm stored metadata
includes marketplace.visible.

Publish Description

Use publish description when install/discover dialog copy should differ from the
normal flow description:

breyta flows update billing-sync \
  --publish-description-file ./publish-description.md

Or inline:

breyta flows update billing-sync \
  --publish-description "## Install this flow"

This markdown is used on install/discover dialog surfaces for installable
flows.
If no publish description is set, install dialogs fall back to the normal
flow description.
Discover cards still use the regular short description preview.

Clear only the publish description:

breyta flows update billing-sync --publish-description ""

Discover Card Media

Use discover card media when public discover/install cards should show a
curated image or video preview instead of only the fallback hero:

breyta flows update billing-sync \
  --publish-media-type image \
  --publish-media-source-kind https-url \
  --publish-media-source https://cdn.example.com/hero.png \
  --publish-media-alt "Billing dashboard preview"

Video media can also include an optional poster:

breyta flows update billing-sync \
  --publish-media-type video \
  --publish-media-source-kind https-url \
  --publish-media-source https://cdn.example.com/demo.mp4 \
  --publish-media-poster-kind https-url \
  --publish-media-poster https://cdn.example.com/demo-poster.jpg \
  --publish-media-alt "Billing reconciliation walkthrough"

Behavior:

publishMedia replaces the whole discover card media value each time you set it
Use --clear-publish-media to remove it explicitly
https-url sources require https://...
flow-resource sources require a same-workspace res://... URI. Use only
reviewed resources intended for public Discover/install card media.
Poster media is optional and only supported for video
If you keep the flow in source control, you can author the same value as :publish-media in the .clj flow file and push it

Clear discover card media:

breyta flows update billing-sync --clear-publish-media

Public Discover Visibility

Use these commands when the flow should appear in discover/install surfaces:

breyta flows discover list
breyta flows discover search billing
breyta flows discover update billing-sync --public=true

Important distinctions:

breyta flows discover list and discover search browse the public
installable catalog for the current workspace.
breyta flows search is separate. It searches actual workspace flow metadata,
not the public discover/install catalog. Approved reusable templates live
under breyta flows templates search.
Public discover requires explicit public visibility and a released installable flow.
Public app page proof uses the marketing route
https://breyta.ai/apps/<flow-slug>. Keep it distinct from workspace install
URLs such as /<workspace-id>/flows/<slug>/installations.
Public listings can include manual interfaces, schedules, and webhook
interfaces. Webhook interface setup is managed per installation. Legacy
triggers remain visible for existing flows.

Paid Monetization

For normal creator work, use the flow Publish page:

/<workspace-id>/flows/<slug>/publish

The Publish page saves public listing, paid pricing, optional trial, and live
publish state together. Paid checkout from the app path is before install for
one-time and subscription flows. Usage pricing is stored as before-run
monetization metadata while run metering and Stripe usage invoicing are rolled
out.
Source-first authoring remains useful for code-reviewed flow definitions,
fixtures, and CLI-heavy operations. New paid apps should use an app-owned
catalog in source:

{:slug :customer-insights
 :name "Customer Insights"
 :tags ["analytics" "customer-insights"]
 :discover {:public true}
 :marketplace
 {:visible true
  :app
  {:app-id "customer-insights-suite"
   :app-name "Customer Insights"
   :app-primary-flow-slug "customer-insights"
   :app-flow-slugs ["customer-insights"]
   :monetization
   {:plans
    [{:plan-id "starter"
      :name "Starter"
      :default true
      :pricing {:type "subscription"
                :amount 29
                :currency "usd"
                :interval "month"}
      :trial {:days 7
              :payment-method-required false}}
     {:plan-id "pro-pack"
      :name "Pro Pack"
      :pricing {:type "usage"
                :amount 49
                :currency "usd"
                :unit "run"
                :included-quantity 250}}]}}}}

Pricing model summary:

:free: no paid gate
:one-time: one upfront purchase for paid access
:subscription: recurring access subscription
:usage: prepaid run pack paid once for a fixed number of successful runs
:subscription-usage: recurring subscription with a fixed run allowance each billing period

Run-counted behavior:

successful completed runs consume allowance
failed, cancelled, terminated, and timed-out runs do not consume allowance
:usage allowance does not expire by time
:subscription-usage allowance resets on renewal
:subscription-usage overages are not billed yet; exhaustion blocks further runs until renewal

Supported values:

pricing.type: :free, :one-time, :subscription, :usage, :subscription-usage
pricing.amount: positive price in major currency units. Decimals are allowed when the currency supports them, for example "0.99" USD.
pricing.currency: lowercase ISO code such as "usd"
pricing.interval: :month or :year for subscriptions and subscription usage
pricing.unit: :run for usage and subscription usage
pricing.free-quantity: zero or more free trial runs for :usage, or fallback no-card trial runs for :subscription-usage when trial.runs is not set
pricing.included-quantity: positive paid run quantity for :usage, or positive included runs per billing period for :subscription-usage
paywall.when: :before-install or :before-run for paid flows
trial.days: positive integer, optional
trial.payment-method-required: true or false, optional
plans: app-owned catalog entries under
:marketplace {:app {:monetization {:plans [...]}}}. Every plan must
normalize to a unique stable plan-id, every entry must be valid, and at
most one plan can be marked default or recommended. If no default is set,
the first plan is treated as the default.
Seat-based pricing is not implemented. Do not describe a plan as "N seats" or
"N installs" unless the product has added explicit seat entitlements. Use
run quantities only for usage-priced plans.

Trial compatibility:

:subscription uses trial.days
:one-time and :usage use trial.runs
:subscription-usage can use explicit trial.runs
if :subscription-usage omits trial.runs, pricing.free-quantity acts as the fallback no-card trial-run allowance
if both are present on :subscription-usage, explicit trial.runs wins

Legacy flow-level examples, supported for existing listings:

{:tags ["billing" "automation"]
 :marketplace {:visible true
               :monetization {:pricing {:type :subscription
                                        :amount 25
                                        :currency "usd"
                                        :interval :month}
                              :paywall {:when :before-install}
                              :trial {:days 7
                                      :payment-method-required true}}}
 :discover {:public true}
 ...}

{:tags ["usage" "automation"]
 :marketplace {:visible true
               :monetization {:pricing {:type :usage
                                        :amount 100
                                        :currency "usd"
                                        :unit :run
                                        :included-quantity 500}
                              :paywall {:when :before-run}
                              :trial {:runs 5
                                      :payment-method-required false}}}
 :discover {:public true}
 ...}

{:tags ["catalog"]
 :marketplace {:visible true
               :monetization {:pricing {:type :subscription-usage
                                        :amount 49
                                        :currency "usd"
                                        :interval :month
                                        :unit :run
                                        :included-quantity 100}
                              :paywall {:when :before-run}}}
 :discover {:public true}
 ...}

If you operate directly against /api/commands, the underlying monetization
command is flows.marketplace.monetization.update, but source-authored paid
apps should prefer the app-owned catalog shape above. CLI metadata update
commands set visibility and other metadata; they do not replace the source
plan-catalog authoring path.
For day-to-day paid-flow publishing, prefer the Publish page so saved metadata
and the live buyer version do not drift.

For seller onboarding and payout prerequisites, see Paid Public Flows.

Public Flow Checklist

If the flow is a new paid app, add
:marketplace {:app {... :monetization {:plans [...]}}} in source. Keep
legacy :marketplace {:monetization {...}} only when preserving an existing
legacy listing.
Make every connection requirement ownership explicit, including
:type :secret requirements:
- Use :provided-by :author for author-owned credentials the public flow
  should run with, such as Apify or OpenAI.
- Use :provided-by :installer for user-owned accounts each installer must
  connect themselves.
- Public release checks reject connection slots that omit :provided-by.
Configure and check author-owned live bindings before release:
- breyta flows configure <slug> --target live --version latest --set <slot>.conn=<connection-id>
- breyta flows configure check <slug> --target live --version latest
Add install-surface copy and discover card media when the public surface should be polished:
- Install dialog markdown: breyta flows update <slug> --publish-description-file ./publish-description.md
- Discover card hero: breyta flows update <slug> --publish-media-type image --publish-media-source-kind https-url --publish-media-source https://...
Choose one marketplace visibility path:
- Source-first: add :marketplace {:visible true} to the flow definition before push only after explicit approval.
- Explicit after push: run breyta flows marketplace update <slug> --visible=true only after explicit approval.
Choose one discover visibility path:
- Source-first: add :discover {:public true} to the flow definition before
  push only after explicit approval.
- Explicit after push: run breyta flows discover update <slug> --public=true after the flow has been pushed and only after explicit approval.
Push the flow.
If you chose an explicit marketplace/discover path, run those updates after push.
Release or promote so there is an installable live version.
Verify it in the web Discover UI, or with breyta flows discover list /
breyta flows discover search <query>.
Verify the marketing app page at https://breyta.ai/apps/<flow-slug>.

Ordering Notes

groupOrder is explicit manual metadata. Lower numbers sort first.
Use spaced values such as 10, 20, 30 so future insertions are easy.
flows show --pretty returns sibling groupFlows ordered by explicit
groupOrder when present.

Live Binding Promotion

Use this command when live bindings should start from the draft target:

breyta flows configure billing-sync \
  --target live \
  --from-draft \
  --version latest