Create Workflows

Overview

Create workflows programmatically using the Kadoa SDK, CLI, MCP Server, or REST API:

Create workflows with natural language prompts
Use existing schemas or define custom ones
Configure monitoring and scheduling options

Prerequisites

Before you begin, you’ll need:

A Kadoa account
Your API key
For SDK: npm install @kadoa/node-sdk or yarn add @kadoa/node-sdk or uv add kadoa-sdk

Authentication

import { KadoaClient } from '@kadoa/node-sdk';

const client = new KadoaClient({
  apiKey: 'YOUR_API_KEY'
});

const status = await client.status();
console.log(status);
console.log(status.user);

import asyncio
from kadoa_sdk import KadoaClient, KadoaClientConfig

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

status = asyncio.run(client.status())
print(status)
print(status.user)

# Interactive OAuth login (saves to ~/.kadoa/config.json)
kadoa login

# Or provide both OAuth tokens for non-interactive refresh
export KADOA_ACCESS_TOKEN=YOUR_ACCESS_TOKEN
export KADOA_REFRESH_TOKEN=YOUR_REFRESH_TOKEN

# Check auth status
kadoa whoami

A tk-... API key authenticates SDK and local MCP requests, but it is not a CLI token.

The remote server at mcp.kadoa.com/mcp uses OAuth, so no API key is needed.
For local stdio mode, set KADOA_API_KEY in your client config or run `kadoa login` (shared with the CLI).

const headers = {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json"
};

Extraction Methods

Choose how you want to extract data from websites:

Auto Mode

The simplest way of creating a workflow is by simply passing a URL. Kadoa will automatically suggest a data schema and extract all relevant data from the page.

// SDK: AI automatically detects and extracts data
const result = await client.extraction.run({
  urls: ["https://sandbox.kadoa.com/ecommerce"]
});

console.log(result.data);

from kadoa_sdk import ExtractionOptions, KadoaClient, KadoaClientConfig

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

# SDK: AI automatically detects and extracts data
result = client.extraction.run(
    ExtractionOptions(
        urls=["https://sandbox.kadoa.com/ecommerce"]
    )
)

print(result.data)

> "Extract all products from https://sandbox.kadoa.com/ecommerce"

// API: Describe the extraction in plain language
// POST https://api.kadoa.com/v4/workflows
{
  "urls": ["https://sandbox.kadoa.com/ecommerce"],
  "name": "Auto Product Extraction",
  "userPrompt": "Extract all product information including name, price, availability, and any other relevant details"
}

// Or define a minimal schema:
{
  "urls": ["https://sandbox.kadoa.com/ecommerce"],
  "name": "Auto Product Extraction",
  "entity": "Product",
  "fields": [
    {
      "name": "data",
      "dataType": "STRING",
      "description": "Extract all product information"
    }
  ]
}

Custom Schema

Define exactly what fields you want to extract for precise control:

const workflow = await client
  .extract({
    urls: ["https://sandbox.kadoa.com/ecommerce"],
    name: "Structured Product Extraction",
    extraction: (builder) =>
      builder
        .entity("Product")
        .field("title", "Product name", "STRING", {
          example: "iPhone 15 Pro",
        })
        .field("price", "Price in USD", "MONEY")
        .field("inStock", "Availability", "BOOLEAN")
        .field("rating", "Rating 1-5", "NUMBER")
        .field("releaseDate", "Launch date", "DATE"),
  })
  .create();

const result = await workflow.run({ limit: 10 });

// Use destructuring for cleaner access
const { data } = await result.fetchData({});
console.log(data);

from kadoa_sdk import (
    ExtractOptions,
    FieldOptions,
    KadoaClient,
    KadoaClientConfig,
    RunWorkflowOptions,
)

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

workflow = (
    client.extract(
        ExtractOptions(
            urls=["https://sandbox.kadoa.com/ecommerce"],
            name="Structured Product Extraction",
            extraction=lambda builder: builder.entity("Product")
            .field("title", "Product name", "STRING", FieldOptions(example="iPhone 15 Pro"))
            .field("price", "Price in USD", "MONEY")
            .field("inStock", "Availability", "BOOLEAN")
            .field("rating", "Rating 1-5", "NUMBER")
            .field("releaseDate", "Launch date", "DATE"),
        )
    )
    .create()
)

result = workflow.run(RunWorkflowOptions(limit=10))

# Use destructuring for cleaner access
response = result.fetch_data({})
print(response.data)

> "Extract product title, price in USD, availability, rating, and release date from https://sandbox.kadoa.com/ecommerce"

// POST https://api.kadoa.com/v4/workflows
{
  "urls": ["https://sandbox.kadoa.com/ecommerce"],
  "name": "Structured Product Extraction",
  "entity": "Product",
  "fields": [
    {
      "name": "title",
      "dataType": "STRING",
      "description": "Product name"
    },
    {
      "name": "price",
      "dataType": "MONEY",
      "description": "Price in USD"
    },
    {
      "name": "inStock",
      "dataType": "BOOLEAN",
      "description": "Availability"
    },
    {
      "name": "rating",
      "dataType": "NUMBER",
      "description": "Rating 1-5"
    },
    {
      "name": "releaseDate",
      "dataType": "DATE",
      "description": "Launch date"
    }
  ]
}

Available Data Types: STRING, NUMBER, BOOLEAN, DATE, DATETIME, MONEY, IMAGE, LINK, OBJECT, ARRAY See all data types →

Classification

Automatically categorize content into predefined classes:

const workflow = await client
  .extract({
    urls: ["https://sandbox.kadoa.com/news"],
    name: "Article Classifier",
    extraction: (builder) =>
      builder
        .entity("Article")
        .field("title", "Headline", "STRING", {
          example: "Tech Company Announces New Product",
        })
        .field("content", "Article text", "STRING", {
          example: "The article discusses the latest innovations...",
        })
        .classify("sentiment", "Content tone", [
          { title: "Positive", definition: "Optimistic tone" },
          { title: "Negative", definition: "Critical tone" },
          { title: "Neutral", definition: "Balanced tone" },
        ])
        .classify("category", "Article topic", [
          { title: "Technology", definition: "Tech news" },
          { title: "Business", definition: "Business news" },
          { title: "Politics", definition: "Political news" },
        ]),
  })
  .create();
//Note: 'limit' here is limiting number of extracted records not fetched
const result = await workflow.run({ limit: 10, variables: {} });
console.log(result.jobId);
const data = result.fetchData({ limit: 10 });
console.log(data);

from kadoa_sdk import (
    ExtractOptions,
    FieldOptions,
    KadoaClient,
    KadoaClientConfig,
    RunWorkflowOptions,
)

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

workflow = (
    client.extract(
        ExtractOptions(
            urls=["https://sandbox.kadoa.com/news"],
            name="Article Classifier",
            extraction=lambda builder: builder.entity("Article")
            .field(
                "title",
                "Headline",
                "STRING",
                FieldOptions(example="Tech Company Announces New Product"),
            )
            .field(
                "content",
                "Article text",
                "STRING",
                FieldOptions(example="The article discusses the latest innovations..."),
            )
            .classify(
                "sentiment",
                "Content tone",
                [
                    {"title": "Positive", "definition": "Optimistic tone"},
                    {"title": "Negative", "definition": "Critical tone"},
                    {"title": "Neutral", "definition": "Balanced tone"},
                ],
            )
            .classify(
                "category",
                "Article topic",
                [
                    {"title": "Technology", "definition": "Tech news"},
                    {"title": "Business", "definition": "Business news"},
                    {"title": "Politics", "definition": "Political news"},
                ],
            ),
        )
    )
    .create()
)
# Note: 'limit' here is limiting number of extracted records not fetched
result = workflow.run(RunWorkflowOptions(limit=10, variables={}))
print(result.job_id)
data = result.fetch_data({"limit": 10})
print(data)

// API example coming soon

Prompts

Every workflow is driven by a prompt: a plain-language description of what to extract and how to get there. The AI agent handles navigation, pagination, clicking, and forms automatically. For details, see Prompts.

Navigation is handled automatically when you provide a prompt.

Using a Prompt

For multi-step or complex extractions, write a prompt in plain language. The AI agent follows your prompt to navigate, interact, and extract:

const workflow = await client
  .extract({
    urls: ["https://sandbox.kadoa.com/ecommerce"],
    name: "Product Catalog",
    userPrompt: "Extract all products. Click 'Next' to continue through pagination. For each product, open the detail page and extract the full description and specifications.",
    extraction: (builder) =>
      builder
        .entity("Product")
        .field("title", "Product name", "STRING", {
          example: "Wireless Headphones",
        })
        .field("price", "Product price", "MONEY")
        .field("description", "Full description", "STRING", {
          example: "Over-ear headphones with active noise cancellation",
        })
        .field("specifications", "Technical specs", "STRING", {
          example: "Bluetooth 5.3, 30-hour battery life",
        }),
  })
  .create();

const result = await workflow.run({ limit: 50 });

from kadoa_sdk import (
    ExtractOptions,
    FieldOptions,
    KadoaClient,
    KadoaClientConfig,
    RunWorkflowOptions,
)

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

workflow = (
    client.extract(
        ExtractOptions(
            urls=["https://sandbox.kadoa.com/ecommerce"],
            name="Product Catalog",
            user_prompt="Extract all products. Click 'Next' to continue through pagination. For each product, open the detail page and extract the full description and specifications.",
            extraction=lambda builder: builder.entity("Product")
            .field("title", "Product name", "STRING", FieldOptions(example="Wireless Headphones"))
            .field("price", "Product price", "MONEY")
            .field(
                "description",
                "Full description",
                "STRING",
                FieldOptions(example="Over-ear headphones with active noise cancellation"),
            )
            .field(
                "specifications",
                "Technical specs",
                "STRING",
                FieldOptions(example="Bluetooth 5.3, 30-hour battery life"),
            ),
        )
    )
    .create()
)

result = workflow.run(RunWorkflowOptions(limit=50))

> "Extract all products from https://sandbox.kadoa.com/ecommerce including title, price, description, and specs. Navigate through pagination and open detail pages."

// POST https://api.kadoa.com/v4/workflows
{
  "urls": ["https://sandbox.kadoa.com/ecommerce"],
  "name": "Product Catalog",
  "userPrompt": "Extract all products. Click 'Next' to continue through pagination. For each product, open the detail page and extract the full description and specifications.",
  "entity": "Product",
  "fields": [
    { "name": "title", "dataType": "STRING", "description": "Product name" },
    { "name": "price", "dataType": "MONEY", "description": "Product price" },
    { "name": "description", "dataType": "STRING", "description": "Full description" },
    { "name": "specifications", "dataType": "STRING", "description": "Technical specs" }
  ]
}

Learn how to write effective prompts →

Complex multi-step extractions can take significantly longer to complete (usually around an hour). We recommend avoiding waiting for results synchronously.

Writing Prompts

Write clear, step-by-step prompts for complex extraction tasks. The AI agent follows your prompt autonomously, handling clicks, forms, pagination, and file downloads. Learn how to write effective prompts →

Create from a Template

If your team has templates set up, you can create a workflow and link it to a template. The template’s prompt, schema, and notification settings are applied to the workflow.

> "Create a workflow from the 'Job Listing' template for https://example.com/careers"

// Step 1: Create the workflow as usual
// POST https://api.kadoa.com/v4/workflows
{
  "urls": ["https://example.com/careers"],
  "name": "Example Careers"
}

// Step 2: Link it to a template (applies template config)
// POST https://api.kadoa.com/v4/templates/template-123/link
{
  "workflowIds": ["workflow-456"]
}

Linking applies the template’s latest version. The template-managed parts become read-only on the workflow. See Templates for full details.

Next Steps

Manage Workflows → - List, retrieve, pause, and delete workflows
Schedule & Run Workflows → - Configure intervals, manual execution, and check status
Writing Prompts → - Write effective prompts for complex extraction tasks
Working with Schemas → - Create and manage reusable schemas
Templates → - Reuse configurations across workflows
Data Delivery → - Retrieve extracted data
API Reference →

Foundations

Security & Compliance

Build with UI

Build with Code

Integrations

Overview

Prerequisites

Authentication

Extraction Methods

Auto Mode

Custom Schema

Classification

Prompts

Using a Prompt

Writing Prompts

Create from a Template

Next Steps

​Overview

​Prerequisites

​Authentication

​Extraction Methods

​Auto Mode

​Custom Schema

​Classification

​Prompts

​Using a Prompt

​Writing Prompts

​Create from a Template

​Next Steps

Overview

Prerequisites

Authentication

Extraction Methods

Auto Mode

Custom Schema

Classification

Prompts

Using a Prompt

Writing Prompts

Create from a Template

Next Steps