Templates

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:

Run the same extraction logic across multiple websites
Want to roll out prompt or schema changes to many workflows at once
Need versioned configurations with the ability to roll back
Share standardized extraction setups across your team

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

Create a Template

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

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

curl -X POST "https://api.kadoa.com/v4/templates" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Job Listing",
    "description": "Extracts job postings with title, company, and location"
  }'

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

List Templates

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

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

curl -X GET "https://api.kadoa.com/v4/templates" \
  -H "x-api-key: YOUR_API_KEY"

> "List my templates"

Get a Template

Retrieve a template by ID, including all published versions:

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

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

curl -X GET "https://api.kadoa.com/v4/templates/TEMPLATE_ID" \
  -H "x-api-key: YOUR_API_KEY"

> "Show me the details of the Job Listing template"

Update a Template

Modify a template’s name or description:

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

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

curl -X PUT "https://api.kadoa.com/v4/templates/TEMPLATE_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Job Listing",
    "description": "Now includes salary range"
  }'

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

Delete a Template

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

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

curl -X DELETE "https://api.kadoa.com/v4/templates/TEMPLATE_ID" \
  -H "x-api-key: YOUR_API_KEY"

> "Delete the Job Listing template"

Versioning

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

Publish a New Version

Each version can include prompt, schema fields, data validation rules, and notification settings:

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

curl -X POST "https://api.kadoa.com/v4/templates/TEMPLATE_ID/versions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      }
    ]
  }'

> "Add a new version to the Job Listing template with a salary field"

Version Parameters

Parameter	Description
`prompt`	User prompt to copy into linked workflows
`schemaFields`	Inline schema fields (mutually exclusive with `schemaId`)
`schemaId`	Reference an existing saved schema (mutually exclusive with `schemaFields`)
`schemaEntity`	Entity name for the schema
`dataValidation`	Validation config and rules (`regex`, `custom_sql`, or `llm`)
`notifications`	Notification event-to-channel mappings

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.

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

from kadoa_sdk.workflows import CreateWorkflowInput

workflow = client.workflow.create(
    CreateWorkflowInput(
        urls=["https://example.de/jobs"],
        template_id="TEMPLATE_ID",
        user_prompt="Only include German-language listings and skip archived roles",
    )
)

curl -X POST "https://api.kadoa.com/v4/workflows" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.de/jobs"],
    "templateId": "TEMPLATE_ID",
    "userPrompt": "Only include German-language listings and skip archived roles"
  }'

> "Create a workflow from the Job Listing template for https://example.de/jobs. 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

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

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

curl -X GET "https://api.kadoa.com/v4/templates/TEMPLATE_ID/workflows" \
  -H "x-api-key: YOUR_API_KEY"

> "Show me the workflows linked to the Job Listing template"

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:

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

curl -X POST "https://api.kadoa.com/v4/templates/from-workflow" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "WORKFLOW_ID",
    "name": "Product Scraper",
    "description": "Created from existing product extraction workflow"
  }'

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

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:

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

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

curl -X GET "https://api.kadoa.com/v4/templates/TEMPLATE_ID/schemas" \
  -H "x-api-key: YOUR_API_KEY"

> "Show me the schemas for the Job Listing template"

Foundations

Security & Compliance

Build with UI

Build with Code

Integrations

Prerequisites

When to Use Templates

Create a Template

List Templates

Get a Template

Update a Template

Delete a Template

Versioning

Publish a New Version

Version Parameters

Create a Workflow from a Template

List Linked Workflows

Save from Workflow

List Template Schemas

​Prerequisites

​When to Use Templates

​Create a Template

​List Templates

​Get a Template

​Update a Template

​Delete a Template

​Versioning

​Publish a New Version

​Version Parameters

​Create a Workflow from a Template

​List Linked Workflows

​Save from Workflow

​List Template Schemas

Prerequisites

When to Use Templates

Create a Template

List Templates

Get a Template

Update a Template

Delete a Template

Versioning

Publish a New Version

Version Parameters

Create a Workflow from a Template

List Linked Workflows

Save from Workflow

List Template Schemas