Recipe artifact reference

Workflow recipe schema.

A recipe declares setup inputs and one or more supported resources. Validation normalizes those resources into the same payloads used by Gent's APIs. YAML is the default artifact format; TOML remains supported.

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 supported resource, such as a workflow, label, alert, or retrieval source bucket.

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
  webhook_url:
    type: url
    required: true
    label: Webhook URL
  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.

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: route_leads
      name: Route lead mail
      inbox_id: "{{ inputs.inbox_id }}"
      trigger: email_received
      conditions:
        - field: from_domain
          op: eq
          value: example.com
      writes:
        - source:
            from: trigger.email
          target:
            type: email.add_label
            label_id: "{{ inputs.lead_label_id }}"
        - source:
            from: trigger.email
          target:
            type: webhook
            url: "{{ inputs.crm_webhook_url }}"

Placeholders

How values are resolved.

{{ inputs.name }} resolves from values supplied in the dashboard or validation request.
{{ resources.key.workflow_id }} resolves after a workflow resource with that key is created.
The validation response keeps resource ID placeholders so an installer can replace them after creating earlier resources.
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

{
  "format": "yaml",
  "content": "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": {
    "workflow": []
  },
  "diagnostics": []
}

Diagnostics

Common validation codes.

Code	Meaning
`invalid_yaml`	The file could not be parsed as YAML.
`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_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.