Workflow Recipe TOML Reference

Top level

Required recipe fields.

Field	Required	Description
`schema_version`	Yes	Current public version is `2026-06-18`.
`kind`	Yes	Must be `gent.workflow_recipe`.
`name`	Recommended	Human-readable recipe name shown in preview and review records.
`description`	No	Short explanation of the workflow the recipe describes.
`category`	No	Grouping label for browsing or internal organization.
`inputs`	No	Setup values that may be referenced with `{{ inputs.name }}`.
`resources`	Yes	At least one `sequence`, `work_route`, or `workflow` resource.

Inputs

Values supplied at validation or setup time.

Input example

Secret inputs may be declared, but the recipe file must not include a default or value for them.

[inputs.inbox_id]
type = "inbox"
required = true
label = "Agent inbox"

[inputs.webhook_url]
type = "url"
required = true
label = "Webhook URL"

[inputs.shared_secret]
type = "secret"
required = true
label = "Webhook signing secret"

Property	Description
`type`	UI hint. Common values are `text`, `inbox`, `url`, `email`, `label`, and `secret`.
`required`	When true, validation returns `missing_input` until a value is supplied.
`label`	Human-readable label for the dashboard input.
`default` or `value`	Allowed for non-secret inputs. For `secret` inputs, these are rejected with `secret_in_recipe`.

Resources

What a recipe can create.

Sequence resource

Creates a sequence through POST /v1/sequences/. Sequences are installed before workflows so later resources can reference their IDs.

[[resources.sequence]]
key = "lead_followup"
name = "Lead follow-up"
sender_inbox_id = "{{ inputs.inbox_id }}"
exit_on_reply = true
emails = [
  { delay_days = 2, subject = "Following up", body = "Checking whether this is useful." }
]

Work route resource

Creates a concrete email-based approval, acknowledgement, or text-response route through POST /v1/work-routes/. Include start = true only when the route should begin immediately.

[[resources.work_route]]
key = "finance_signoff"
creator_inbox_id = "{{ inputs.inbox_id }}"
title = "Approve invoice"
request_type = "approval"
routing_mode = "parallel"
completion = "required"
failure_mode = "block"
due_at = "{{ inputs.due_at }}"
start = false
recipients = [
  { kind = "email", email = "finance@example.com" }
]

Workflow resource

Creates a workflow rule through POST /v1/workflows/. Actions are validated against the current workflow reference for the user's plan and permission level.

[[resources.workflow]]
key = "start_followup"
name = "Start follow-up for leads"
inbox_id = "{{ inputs.inbox_id }}"
trigger = "email_received"
conditions = [
  { field = "from_domain", op = "eq", value = "example.com" }
]
writes = [
  { source = { from = "trigger.email" }, target = { type = "sequence.enroll", sequence_id = "{{ resources.lead_followup.sequence_id }}" } }
]

Placeholders

How values are resolved.

{{ inputs.name }} resolves from values supplied in the dashboard or validation request.
{{ resources.key.sequence_id }} resolves after a sequence resource with that key is created.
{{ resources.key.route_id }} resolves after a work-route resource with that key is created.
The validation response keeps resource ID placeholders such as {{ resources.key.sequence_id }} so an installer can replace them after creating earlier resources.
Resource placeholders should be used only by resources created later in the order: sequences, then work routes, then workflows.
Unresolved input placeholders return an unresolved_placeholder diagnostic and block safe setup.

Validation API

Preview without creating anything.

POST/v1/workflows/recipes/validate/

Requires workflows:read. The endpoint returns HTTP 200 with diagnostics, even when valid is false.

Request

{
  "toml": "schema_version = \"2026-06-18\"\nkind = \"gent.workflow_recipe\"\n...",
  "inputs": {
    "inbox_id": "inb_123",
    "webhook_url": "https://example.com/webhook"
  }
}

Response shape

{
  "valid": true,
  "recipe_hash": "sha256:...",
  "schema_version": "2026-06-18",
  "kind": "gent.workflow_recipe",
  "name": "Route leads",
  "inputs": {},
  "resources": {
    "sequence": [],
    "work_route": [],
    "workflow": []
  },
  "diagnostics": []
}

Diagnostics

Common validation codes.

Code	Meaning
`invalid_toml`	The file could not be parsed as TOML.
`invalid_kind`	`kind` is missing or not `gent.workflow_recipe`.
`missing_schema_version`	The recipe does not declare `schema_version`.
`missing_input`	A required input was not supplied.
`secret_in_recipe`	A secret input tried to store a value or default in the recipe file.
`unresolved_placeholder`	A placeholder could not be resolved from inputs or created resources.
`duplicate_resource_key`	Two resources of the same kind share the same key.
`invalid_sequence_payload`	The normalized sequence payload failed sequence API validation.
`invalid_work_route_payload`	The normalized work-route payload failed work-route API validation.
`invalid_workflow_payload`	The normalized workflow payload failed workflow-rule API validation.
`legacy_workflow_write_targets`	The recipe used old `actions` instead of current `writes`.
`unavailable_write_target`	The write target is not available for the user's plan or permission level.
`incompatible_write_target`	The write target cannot run for the selected trigger.
`incompatible_source`	The selected source cannot be satisfied by the selected trigger context.

Menu