Recipe schema

This page is a short list of the main recipe fields. It is for people who write recipes. Want the story version first? Read Authoring recipes.

#Envelope

The envelope is the outer shell of a recipe. Here is one with the fields this page covers:

{
  "recipe_id": "detect-deal-risk-hubspot",
  "version": 1,
  "ttl": 600,
  "metadata": {},
  "variables": {},
  "requires": [],
  "depends_on": [],
  "chat_exposed": false,
  "trigger": [],
  "event_triggers": [],
  "webhook_triggers": [],
  "auto_run": null,
  "trigger_steps": null,
  "run_mode": null,
  "provenance": true,
  "prefetch_steps": [],
  "steps": [],
  "output": {}
}

#Envelope fields

#Envelope fields for triggers, steps, and output

#metadata

#Steps

{
  "id": "risky",
  "transform": "filter",
  "array": "{{step.deals}}",
  "field": "stage",
  "operator": "equal",
  "value": "at_risk",
  "skip_when": "{{step.deals}} is_empty"
}

Recued tells the kind of step from which field is present:

#Step execution flow

Every step runs the same way:

skip_when? → compute → step.<id> = result → fail_on?

• If skip_when is true, the step stores null. The recipe goes on.
• fail_on is checked after the step computes. If it is true, the recipe stops.
• foreach runs the step once for each item in a list. Inside, {{item.*}} is that item. The output is one envelope per item: { ok, result?, error?, item }. They keep the input's order.
• A prefetch step can also say "optional": true. Then a failure stores null instead of stopping the run.

Trigger steps (trigger_steps) have the same shape. Every one must return should_run: true, or the tick stops. Their outputs land on {{trigger.<id>.*}} for the steps after them.

#Variables

A variable has two forms. A bare value is a setting you tuned. Recued works out its type. The one-time run form does not ask about it. An object is a question for the person who runs the recipe. It gets its own box on that form.

"variables": {
  "recipient":  { "label": "Send to", "type": "text" },
  "window":     { "label": "Window", "type": "enum", "options": ["7d", "30d"] },
  "max_rows":   50,
  "deal_id":    null
}

You can still change a tuned setting in the places where tuning belongs. Those are the install dialog, the recipe editor, and the Schedule and Trigger tabs. There, "run every night with window: 30d" is a real setup choice. Only the one-time run form stops asking.

#Object-form fields

These are the only fields there are. Any other field is refused when you install. So a made-up field fails loudly. It is never quietly ignored.

There is no required field. The optional field is the one that exists. Leave it out, and the value is already required. There is no pattern field either. To check the shape of a value, use a guard step. A variable says what a value is called and how to collect it. It never says what counts as valid.

#Types

The field list is closed, but type is open. These types each get their own kind of box:

text · number · boolean · enum (with options) · datetime · date · url · secret · oauth · file_slug · file_ref · file_ref[] · record_ref · mail_template

datetime is one moment. The form sends it with the time zone of the person filling it in, like 2026-10-01T09:30:00+02:00. date is a day, like 2026-10-01. It has no time and no time zone. Use it for a due date or a target date.

record_ref is one of your stored rows. You pick it from a search. mail_template is one of your mail templates. It is a setting of the recipe, never a question for one run.

These are allowed too, and many recipes use them. The form shows each of them as a plain text box. An array with options shows boxes to tick instead:

string · array · object · json · connection

string is the most common type in shipped recipes. It works like text. Any other non-empty string installs and shows as text. So the list can grow, and the recipes you already published still work. That is why an unknown type is allowed but an unknown field is not. A type has a safe fallback. A field nobody reads has none.

#A caller may only pass what you declared

A chat request, an MCP call, a button, or a schedule can pass values to your recipe. If it uses a name that is not in variables, the run is refused. The name is not ignored. So declare every argument you want to accept. And remove any old name you no longer read.

Give a default only when a good one exists. A required input with a filler default is not really required. An empty string, a zero, or an empty list is a filler. The caller can leave it out, and the recipe runs with the filler.

#Value system

"literal"              → use as-is
"{{ref}}"              → resolve, preserve type
"{{ref:format}}"       → resolve; the hint applies only during interpolation
"text {{ref}} text"    → interpolate → string
10, true, false        → native JSON type
null                   → required from caller

The format hints are :currency, :number, :date, :relative, and :percent.

#Conditions

A condition is a short string. One condition per field. One operator per condition. Plain values have no quotes: write equal closed_won, never equal 'closed_won'.

The object form, for a list value:

{ "field": "{{step.x}}", "operator": "in", "value": ["a", "b"] }

Want to join conditions? Use a transform step, any or all. It stores a true or false. Check that. There is no and or or inside a condition string.

#Namespaces recipes can reference

A namespace is the first part of a {{ref}}. It says where the value comes from.

Only ingredients may use {{vault.*}}. A recipe never sees a secret key. The vendor aliases data.hubspot.*, data.salesforce.*, and data.crm.* read enrichments on CRM records. They work with fixed ids only.

#Context fields the engine adds

#Transforms

Each transform's settings are listed in the transforms reference. Tier 1 is the small building blocks:

Tier 2 is handy shortcuts built from Tier 1: find, pluck, sum, min_by, max_by, percent, join, and group_by with aggregate.

Two modes are worth knowing. The filter transform takes mode: "all" | "any" plus a conditions list. That checks many conditions in one step. The map transform takes an expression over {{item.*}}. The expression can be one ref, a math expression, or an object template. Add output_field to attach the answer to each item instead of replacing the item.

#AI functions

Batch mode: every function except ai-compare can take a list as llm.data, plus a non-empty llm.id_field. That is one model call. It gives back one answer per item, in the same order as the input. Each answer is the source record merged with the result fields. The model hints are fast, quality, and thinking.

#Output

"output": {
  "render": [
    { "type": "summary", "source": "step.overview", "label": "Overview" },
    { "type": "ai_analysis", "source": "step.analysis" }
  ]
}

This only routes. There is no logic here. A null source is not shown. The section types:

#How output reaches a reader

render is the only way a run's data reaches anyone. A step result that is not sent to a section cannot be seen. Not by a person. Not by a model. Use json when a reader needs to check the work behind a summary.

The filter block is the one section that is not { type, source, label }. It also has three more fields: fields, hidden, and submit. The fields list names the declared variable keys to show as boxes. The hidden list names declared keys that are sent on submit but never shown. A paging cursor (a marker for the next page of results) is the usual one. The submit field is the button text. Every box comes from the variable's own declaration. There is no styling to write.

#When Recued refuses your recipe

When a recipe is refused, Recued names what it did not like. Here are the ones authors meet most:

orphan_step and ttl_below_floor are warnings, not refusals. The first is a step nothing reads. The second is a cache TTL that is lower than the practical floor.

#Naming

Recipe:      {action}-{entity}-{qualifier}-{platform}    detect-deal-risk-hubspot
Ingredient:  {action}-{entity}-{platform}                deal-reader-hubspot
AI:          ai-{function}                               ai-score
Vendor:      {action}-{vendor}                           search-exa

The platform always goes last. That is what lets variant_group fold the copies made for different platforms into one marketplace card.