Templates

Share one versioned configuration across many workflows and roll out changes when you choose.

A template is one configuration that many workflows share, such as a job postings setup for 50 career pages. You change the template once, then apply the change to all linked workflows at once, or to a few first.

What a template contains

A template can include any of these parts:

Part	What it controls
Setup prompt	The starting instructions for Kadoa’s agent when a workflow is created from the template
Schema	The field definitions and entity name
Data quality	The per-field validation rules
Notifications	Event subscriptions and notification channels
Frequency	How often linked workflows run
Record limit	The maximum number of rows each run keeps. The dashboard calls it Row limit

Each part is optional. For example, a template can define only a schema, or a schema and notifications without a prompt.

For what to put in each part and how to roll out changes safely, see Template best practices.

When to use a template

Use a template when you:

• Extract the same kind of data, in the same structure, from many sources. The agent’s route through each site can differ. The schema and rules stay the same.
• Want to roll out prompt, schema, data quality, notification, frequency, or record limit changes to many workflows at once.
• Need versioned configurations that you can roll back.
• Share standardized extraction setups across your team.

For a one-off extraction, define the schema on the workflow itself. It is simpler and needs no template management.

Versions

Every save publishes a new version. You cannot edit a published version. This lets you:

• Roll out updates to linked workflows selectively
• Roll back to a previous version if needed
• See exactly what changed between versions
• Preview the data impact of a new version on a linked workflow before applying it

Linked workflows don’t move to a new version on their own. You decide when to apply it.

Linked workflows

When you create a workflow from a template, or link an existing workflow through the API, Kadoa applies the template’s configuration to it. Every part the template owns becomes read-only on the workflow. In the dashboard, those panels show Controlled by with the template name. You change these parts in the template instead.

To modify a template-managed field on a workflow, either update the template and apply the change, or unlink the workflow first.

The setup prompt works differently. The agent reads it once, when it builds a workflow from the template. A new prompt version only affects workflows built after it. Existing workflows keep the instructions they started with. The other parts reach existing workflows when you apply the version.

Unlinking a workflow preserves its current configuration. The workflow keeps the prompt, schema, rules, notifications, and frequency it had. They become editable again from the workflow itself.

Create a template

Dashboard

1. Select Templates in the sidebar, then select Create template.

2. Enter a Name. To add a description, select Add note.

3. Turn on each part you want the template to manage, and fill it in. Turn on at least one part.

   • Setup prompt: the instructions new workflows start with, such as domain rules, exclusions, and page quirks. Type $ to insert a variable.
   • Schema: the entity name and fields, in the schema editor.
   • Data quality: per-field validation rules. Turn on Schema first.
   • Notifications: event subscriptions and notification channels.
   • Frequency: how often linked workflows run, optionally on weekdays only.
   • Row limit: the maximum number of rows each run keeps.

4. Select Create template. This publishes version 1.

   

SDK & API

You need an API key. Install the Node SDK with npm install @kadoa/node-sdk. Creating a template sets its name and description. To add the parts, publish a version.

Node SDK

const template = await client.template.create({
  name: "Job Listing",
  description: "Extracts job postings with title, company, and location",
});

console.log("Template created:", template.id);

Template management is currently available in the Node SDK. Python SDK support is coming soon.

MCP

Connect your AI tool to the Kadoa MCP server. Then ask it, for example:

> "Create a template called 'Job Listing' for extracting job postings with title, company, and location"

Your AI tool calls create_template, then create_template_version to add the parts.

Save a workflow as a template

Start a template from a workflow you already set up.

Dashboard

1. Open the workflow.
2. Open the workflow menu (…) and select Save as template.
3. Enter a Template name.
4. Under Include, select the parts to copy: Prompt, Schema, Data quality, Notifications, Frequency, and Row limit.
5. Select Create template.

Kadoa links the workflow to the new template. Save as template appears only on workflows that aren’t linked to a template yet.

SDK & API

Pass name to create a new template, or templateId to add a new version to an existing one.

Node SDK

// Create a new template from a workflow
const newTemplate = await client.template.createFromWorkflow({
  workflowId: "WORKFLOW_ID",
  name: "Product Scraper",
  description: "Created from existing product extraction workflow",
});

console.log("Template created:", newTemplate.templateId);
console.log("Version:", newTemplate.version);

To add a new version to an existing template:

Node SDK

const newVersion = await client.template.createFromWorkflow({
  workflowId: "WORKFLOW_ID",
  templateId: "EXISTING_TEMPLATE_ID",
});

console.log("New version added:", newVersion.version);

MCP

Ask your AI tool, for example:

> "Save my 'Product Monitor' workflow as a new template called 'Product Scraper'"

Your AI tool calls save_workflow_as_template.

Create workflows from a template

A workflow created from a template inherits the selected version’s prompt, schema, validation rules, notifications, and frequency. Kadoa links it to the template. Template-managed settings stay read-only on the workflow until you update or unlink the template.

You can add workflow-specific instructions. Kadoa adds them to the template prompt. They stay attached to that workflow when you apply a later template version.

Dashboard

1. Select Add workflow in the sidebar.

2. Select Template below the prompt box and choose a template. To search, type in Filter templates.

3. Review the attached prompt, schema, data quality, notification, and frequency settings. The template’s setup prompt appears under Template setup.

4. Complete the prompt under Workflow-specific instructions.

5. Select the send button to create the workflow.

   

SDK & API

The public field is userPrompt in REST and the SDKs, and prompt in MCP. additionalInstructions is internal. Don’t send it from clients.

Node SDK

const workflow = await client.workflow.create({
  urls: ["https://example.de/jobs"],
  templateId: "TEMPLATE_ID",
  userPrompt: "Only include German-language listings and skip archived roles",
});

Omitting templateVersion resolves the latest published version once, at request time. When the template has no prompt, userPrompt becomes the complete workflow prompt.

MCP

Ask your AI tool, for example:

> "Create a workflow from the Job Listing template for https://example.de/jobs. Only include German-language listings and skip archived roles."

Your AI tool calls create_workflow with the templateId. Its prompt holds only the workflow-specific instructions.

Publish and apply a new version

Publishing a version doesn’t change any linked workflow. You then apply it to the workflows that should move to it.

Dashboard

To publish a version:

1. Select Templates in the sidebar and open the template.
2. Under Config, select Edit.
3. Change any part. To stop managing a part, turn it off.
4. Select Save v.N, where N is the next version number.

To apply it:

1. Select Linked workflows. Workflows behind the latest version show Outdated and appear first.

2. Select Update to v.N on a workflow. To update several, select their checkboxes or Select all. Then select the update button at the top, for example Update 3 to v.4.

3. Review the affected workflows in the dialog. To see the data impact first, select Preview data changes.

4. Select Update.

   

To update one workflow from its own page, open the template actions menu (…) next to Controlled by and select Update to latest version. This is unavailable while the workflow is running.

SDK & API

Each version is a complete snapshot. Send only the parts you want to change. Anything you leave out keeps the previous version’s value. The example below replaces the prompt and schema and keeps the previous rules, notifications, and frequency.

Node SDK

const version = await client.template.createVersion("TEMPLATE_ID", {
  prompt: "Extract job listings including salary information",
  schemaEntity: "JobListing",
  schemaFields: [
    {
      name: "title",
      description: "Job title",
      fieldType: "SCHEMA",
      dataType: "STRING",
    },
    {
      name: "company",
      description: "Company name",
      fieldType: "SCHEMA",
      dataType: "STRING",
    },
    {
      name: "salary",
      description: "Salary range",
      fieldType: "SCHEMA",
      dataType: "STRING",
    },
  ],
});

console.log("Published version:", version.version);

See Version parameters for every part you can set. To find outdated workflows, list the linked workflows and the version each one runs:

Node SDK

const workflows = await client.template.getLinkedWorkflows("TEMPLATE_ID");

for (const workflow of workflows) {
  console.log(`${workflow.workflowId}: ${workflow.workflowName} (version ${workflow.templateVersion})`);
}

To roll the version out, call Apply template update with the targetVersion and the workflowIds to update. To preview the data for one linked workflow first, call Preview schema change.

MCP

Ask your AI tool, for example:

> "Add a new version to the Job Listing template with a salary field"
> "Show me the workflows linked to the Job Listing template"
> "Apply the latest Job Listing version to all outdated workflows"

Your AI tool calls create_template_version, list_template_workflows, and apply_template_version.

Preview data changes

Before you apply, the preview shows how each field changes for a linked workflow. Fields are grouped into Added, Updated, Removed, and Unchanged. If you update several workflows, choose which one to preview under Preview data for.

Workflows with previous runs show existing data for unchanged and removed fields, plus grounded simulations for new and changed fields. Without a previous run, source-backed values remain empty.

What applying a version does

• Changes take effect on the next run. Applying a version updates the configuration and doesn’t start a run. Data already collected is unchanged. To get data with the new configuration now, run the workflow manually.
• Setup prompt changes reach only new workflows. Existing workflows keep the instructions they started with.
• Active real-time monitors are skipped. Pause them first if you want them in the batch.
• To roll back in the dashboard, open the template’s History, find an earlier version, and select Apply.

History lists every version with its publish date and who published it. Select Show changes or Show content on a version to switch between its changes and its full snapshot.

Link or unlink workflows

Workflows are linked when you create them from a template or save them as one. The dashboard has no separate step to link an existing workflow. Use the API or MCP for that. Unlinked workflows keep their current configuration and stop receiving template updates.

Dashboard

1. Open the template and select Linked workflows.
2. Select Unlink on a workflow. To unlink several, select their checkboxes. Then select the unlink button at the top, for example Unlink 3.
3. Select Unlink to confirm.

To unlink from the workflow’s own page, open the template actions menu (…) next to Controlled by and select Unlink workflow.

SDK & API

To link existing workflows, call Link workflows to template with their workflowIds. The template needs at least one published version. Kadoa links the workflows at the latest version and applies its configuration. A workflow that is linked to another template returns a conflict unless you pass force: true.

To unlink workflows, call Unlink workflows from template with their workflowIds.

MCP

Ask your AI tool, for example:

> "Link my Acme Careers workflow to the Job Listing template"

Your AI tool calls link_template_to_workflows. To unlink, it calls unlink_template_from_workflows.

View templates and versions

Dashboard

1. Select Templates in the sidebar. To filter the list, type in Search templates….
2. Select a template to open it.
3. Select Config for the latest version, History for all versions, or Linked workflows.

SDK & API

List your templates:

Node SDK

const templates = await client.template.list();

for (const template of templates) {
  console.log(`${template.id}: ${template.name}`);
}

Retrieve a template by ID, including all published versions:

Node SDK

const template = await client.template.get("TEMPLATE_ID");

console.log(template.name);
console.log(template.description);
console.log(template.versions); // Array of published versions

View the schemas associated with a template’s versions:

Node SDK

const schemas = await client.template.listSchemas("TEMPLATE_ID");

for (const schema of schemas) {
  console.log(`${schema.schemaId}: ${schema.schemaName} (${schema.entity})`);
}

MCP

Ask your AI tool, for example:

> "List my templates"
> "Show me the details of the Job Listing template"
> "Show me the schemas for the Job Listing template"

Your AI tool calls list_templates, get_template, and list_template_schemas.

Duplicate a template

Duplicating is available in the dashboard.

1. Select Templates in the sidebar.
2. Open the actions menu (…) on a template and select Duplicate. The same menu is on the template’s own page.
3. Optionally, enter a New template name. If you leave it empty, the copy gets the original name with a “(Copy)” suffix.
4. Select Duplicate. The new template opens.

The copy is independent and starts at version 1. It takes the latest published version’s prompt, schema, data quality rules, notifications, frequency, and row limit. It doesn’t take the version history or the linked workflows.

Change a template’s name or description

Changing the name or description doesn’t publish a new version. To change the parts, publish a new version.

Dashboard

1. Select Templates in the sidebar and open the template.
2. Under Config, select Edit.
3. Change the Name or the Note.
4. Select Save.

SDK & API

Node SDK

const updated = await client.template.update("TEMPLATE_ID", {
  name: "Updated Job Listing",
  description: "Now includes salary range",
});

console.log("Template updated:", updated.id);

MCP

Ask your AI tool, for example:

> "Update the Job Listing template description to 'Now includes salary range'"

Your AI tool calls update_template.

Delete a template

Deleting a template archives it and unlinks all its workflows. The workflows keep their current configuration but stop receiving template updates.

Dashboard

1. Select Templates in the sidebar.
2. Select the checkbox of each template you want to delete, then select Delete. For one template, you can also open its actions menu (…) and select Delete template.
3. Select Delete to confirm.

SDK & API

Node SDK

await client.template.delete("TEMPLATE_ID");

MCP

Ask your AI tool, for example:

> "Delete the Job Listing template"

Your AI tool calls delete_template, which asks for confirmation first.

Version parameters

These are the parts you can set when you publish a version through the SDK or API.

Parameter	Description
prompt	Setup prompt for workflows created from the template. Each workflow can add its own instructions on top, through the agent or userPrompt
schemaFields	Inline schema fields (mutually exclusive with schemaId)
schemaId	Reference an existing saved schema (mutually exclusive with schemaFields)
schemaEntity	Entity name for the schema
schemaValidationRules	Data quality rules keyed by field name
notifications	Notification event-to-channel mappings
frequency	Run interval, or CUSTOM with cron schedules and a timezone. weekdaysOnly: true skips Saturday and Sunday runs of a repeat interval. For cron, set the weekdays in the expression
recordLimit	Maximum rows each run keeps. recordLimitManaged: false releases the limit back to the workflows

Leave a parameter out to keep the previous version’s value. If you replace the schema and leave out schemaValidationRules, the version keeps only the rules for fields that still exist.

To remove a part from the template, set it to null. Record limit is the exception. Use recordLimitManaged: false to let workflows control their own limits. Setting recordLimit: null keeps the limit template-managed.

Schema fields accept name, description, dataType, an optional instruction, an optional example (a JSON string for OBJECT and ARRAY), and isKey.

Limits

• The dashboard applies a version to at most 100 workflows at a time. For more, contact support.
• API requests that link, unlink, or apply take at most 2,000 workflow IDs each.
• A template frequency can use only one timezone.

Related

• Template best practices: what to put in each part and how to update safely
• Schemas: field kinds and data types
• Data quality: validation rules
• Notifications: event types and channels
• MCP tools: every template tool your AI tool can call
• Templates API reference