> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kadoa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

<Note>
  Templates are currently available in the Node SDK. Python SDK support is coming soon.
</Note>

## 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

<CodeGroup>
  ```typescript Node SDK theme={null}
  const template = await client.template.create({
    name: "Job Listing",
    description: "Extracts job postings with title, company, and location",
  });

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

  ```bash REST API theme={null}
  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"
    }'
  ```

  ```text MCP Server theme={null}
  > "Create a template called 'Job Listing' for extracting job postings with title, company, and location"
  ```
</CodeGroup>

## List Templates

<CodeGroup>
  ```typescript Node SDK theme={null}
  const templates = await client.template.list();

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

  ```bash REST API theme={null}
  curl -X GET "https://api.kadoa.com/v4/templates" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```text MCP Server theme={null}
  > "List my templates"
  ```
</CodeGroup>

## Get a Template

Retrieve a template by ID, including all published versions:

<CodeGroup>
  ```typescript Node SDK theme={null}
  const template = await client.template.get("TEMPLATE_ID");

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

  ```bash REST API theme={null}
  curl -X GET "https://api.kadoa.com/v4/templates/TEMPLATE_ID" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```text MCP Server theme={null}
  > "Show me the details of the Job Listing template"
  ```
</CodeGroup>

## Update a Template

Modify a template's name or description:

<CodeGroup>
  ```typescript Node SDK theme={null}
  const updated = await client.template.update("TEMPLATE_ID", {
    name: "Updated Job Listing",
    description: "Now includes salary range",
  });

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

  ```bash REST API theme={null}
  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"
    }'
  ```

  ```text MCP Server theme={null}
  > "Update the Job Listing template description to 'Now includes salary range'"
  ```
</CodeGroup>

## Delete a Template

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

<CodeGroup>
  ```typescript Node SDK theme={null}
  await client.template.delete("TEMPLATE_ID");
  ```

  ```bash REST API theme={null}
  curl -X DELETE "https://api.kadoa.com/v4/templates/TEMPLATE_ID" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```text MCP Server theme={null}
  > "Delete the Job Listing template"
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```typescript Node SDK theme={null}
  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);
  ```

  ```bash REST API theme={null}
  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"
        }
      ]
    }'
  ```

  ```text MCP Server theme={null}
  > "Add a new version to the Job Listing template with a salary field"
  ```
</CodeGroup>

### 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                                      |

## List Linked Workflows

<CodeGroup>
  ```typescript Node SDK theme={null}
  const workflows = await client.template.listWorkflows("TEMPLATE_ID");

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

  ```bash REST API theme={null}
  curl -X GET "https://api.kadoa.com/v4/templates/TEMPLATE_ID/workflows" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```text MCP Server theme={null}
  > "Show me the workflows linked to the Job Listing template"
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```typescript Node SDK theme={null}
  // 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);
  ```

  ```bash REST API theme={null}
  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"
    }'
  ```

  ```text MCP Server theme={null}
  > "Save my 'Product Monitor' workflow as a new template called 'Product Scraper'"
  ```
</CodeGroup>

To add as a new version to an existing template:

```typescript Node SDK theme={null}
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:

<CodeGroup>
  ```typescript Node SDK theme={null}
  const schemas = await client.template.listSchemas("TEMPLATE_ID");

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

  ```bash REST API theme={null}
  curl -X GET "https://api.kadoa.com/v4/templates/TEMPLATE_ID/schemas" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```text MCP Server theme={null}
  > "Show me the schemas for the Job Listing template"
  ```
</CodeGroup>