Templates

Create and manage reusable workflow templates programmatically using the SDK

Templates let you define reusable configurations (prompt, schema, data validation rules, notification settings, and run frequency) that can be linked to multiple workflows and versioned over time.

Prerequisites

• Kadoa account with API key
• SDK installed: npm install @kadoa/node-sdk

Templates are currently available in the Node SDK. Python SDK support is coming soon.

When to Use Templates

Use templates 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 with the ability to roll back
• Share standardized extraction setups across your team

For guidance on what to put in each part, see Template Best Practices.

For one-off extractions, inline schema definitions are simpler and don’t require template management.

Create a Template

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);

List Templates

Node SDK

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

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

Get a Template

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

Update a Template

Modify a template’s name or description:

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);

Delete a Template

Deleting a template archives it. Existing linked workflows keep their current configuration but are unlinked.

Node SDK

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

Versioning

Templates support versioning so you can iterate on configurations and roll back if needed.

Publish a New Version

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);

Version Parameters

Parameter	Description
prompt	Setup prompt for workflows created from the template. Each workflow can add its own instructions on top, through the Assistant 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
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. To remove a part from the template, set it to null, except for record limit: 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.

Create a Workflow from a Template

A workflow created from a template inherits the selected version’s prompt, schema, validation rules, notifications, and frequency. Optionally pass workflow-specific instructions: they are added to the template prompt and remain attached to that workflow when a later template version is applied.

The public field is userPrompt in REST and the SDKs, and prompt in MCP. additionalInstructions is internal and should not be sent by 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 selected template has no prompt, userPrompt becomes the complete workflow prompt.

List Linked Workflows

Node SDK

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

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

Save from Workflow

Create a template from an existing workflow’s configuration. 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 as 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);

List Template Schemas

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})`);
}