​
Overview

This guide shows you how to create workflows programmatically using the Kadoa API. You’ll learn how to:
  • Create workflows with different navigation modes
  • Use existing schemas or define custom ones
  • Set up AI Navigation with natural language instructions
  • Configure monitoring and scheduling options

​
Prerequisites

Before you begin, you’ll need:
  • A Kadoa account
  • Your API key
  • Basic understanding of REST APIs

​
API Endpoint

All workflow creation requests use: 
POST https://api.kadoa.com/v4/workflows

​
Authentication

Include your API key in the request headers: 
const response = await fetch("https://api.kadoa.com/v4/workflows", {
  method: "POST",
  headers: {
    "x-api-key": "your-api-key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(workflowData)
});
View full API reference → Kadoa supports four navigation modes:
ModeValueDescription
Single Pagesingle-pageExtract data from a single page
Listpaginated-pageNavigate through lists with pagination
List + Detailspage-and-detailNavigate lists then open each item
AI Navigationagentic-navigationAI-driven navigation based on instructions

​
Basic Workflow Examples

​
1. Single Page

Extract job posting from a careers page: 
// POST /v4/workflows
{
  "urls": ["https://example.com/careers/job-123"],
  "navigationMode": "single-page",
  "entity": "Job Postings",
  "fields": [
    {
      "name": "jobTitle",
      "dataType": "STRING",
      "description": "Job title"
    },
    {
      "name": "department",
      "dataType": "STRING",
      "description": "Department or team"
    },
    {
      "name": "location",
      "dataType": "STRING",
      "description": "Job location"
    }
  ],
  "name": "Job Posting Monitor",
  "interval": "DAILY"
}

​
2. List Navigation

Use a pre-built schema to extract a product directory: 
// POST /v4/workflows
{
  "urls": ["https://example.com/products"],
  "navigationMode": "paginated-page",
  "schemaId": "YOUR_SCHEMA_ID",
  "limit": 100,
  "name": "Product Catalog Monitor",
  "interval": "HOURLY"
}

​
3. List + Details Navigation

Extract product listings and their detail pages: 
// POST /v4/workflows
{
  "urls": ["https://example.com/products"],
  "navigationMode": "page-and-detail",
  "entity": "product",
  "fields": [
    {
      "name": "title",
      "dataType": "STRING",
      "description": "Product name"
    },
    {
      "name": "price",
      "dataType": "NUMBER",
      "description": "Product price"
    }
  ],
  "limit": 50,
  "name": "Product Details Extractor"
}

​
AI Navigation

AI Navigation enables autonomous website navigation through natural language instructions. Learn more about AI Navigation →

​
Schema Options

AI Navigation supports three schema approaches:
  1. Existing Schema (schemaId) - Reference a pre-built schema from your account
  2. Custom Schema (entity + fields) - Define specific fields and data types
  3. Auto-Detected Schema (no schema) - Let AI determine what data to extract

​
AI Navigation with Existing Schema

Use a pre-built schema by referencing its ID: 
// POST /v4/workflows
{
  "urls": ["https://example.com"],
  "navigationMode": "agentic-navigation",
  "schemaId": "507f1f77bcf86cd799439020",
  "userPrompt": "Navigate to the careers section, find all job postings for engineering roles, and extract the job details including requirements and benefits. Make sure to click 'Load More' if present to get all available positions.",
  "limit": 100,
  "name": "AI Job Scraper"
}

​
AI Navigation with Custom Schema

Define your own schema fields for precise data extraction: 
// POST /v4/workflows
{
  "urls": ["https://example.com"],
  "navigationMode": "agentic-navigation",
  "entity": "Job Postings",
  "fields": [
    {
      "name": "jobTitle",
      "dataType": "STRING",
      "description": "Job title"
    },
    {
      "name": "description",
      "dataType": "STRING",
      "description": "Job description"
    },
    {
      "name": "requirements",
      "dataType": "STRING",
      "description": "Job requirements"
    },
    {
      "name": "benefits",
      "dataType": "STRING",
      "description": "Benefits offered"
    }
  ],
  "userPrompt": "Navigate to the careers section, find all job postings for engineering roles, and extract the job details including requirements and benefits. Make sure to click 'Load More' if present to get all available positions.",
  "limit": 100,
  "name": "AI Job Scraper"
}

​
AI Navigation with Auto-Detected Schema

Let the AI determine what data to extract based on your instructions: 
// POST /v4/workflows
{
  "urls": ["https://example.com"],
  "navigationMode": "agentic-navigation",
  "userPrompt": "Find all blog posts from 2024. For each post, extract the title, author, publication date, main content, and any tags or categories. Also check if there are comments and extract the comment count.",
  "name": "AI Blog Scraper"
}

​
Writing Effective Prompts

The key to successful AI Navigation is writing clear, step-by-step instructions. View our complete guide to writing AI prompts →

​
Using Variables in AI Navigation

Variables allow you to create dynamic workflows that reference values defined in your dashboard. Variables must be created in the UI first, then referenced in API requests. 
// POST /v4/workflows
{
  "urls": ["https://example.com"],
  "navigationMode": "agentic-navigation",
  "userPrompt": "Navigate to search and loop through '@productTypes', press search, and extract product details for all results.",
  "name": "Dynamic Product Search"
}
Variable Workflow:
  1. Create variables in the dashboard UI: productTypes
  2. Reference them in your userPrompt using @variableName syntax
  3. The backend automatically interpolates variables using the values on your account

​
Bulk Workflow Creation

For creating multiple workflows at once, you can loop through URLs and create a workflow for each one: 
const API_KEY = "YOUR_API_KEY";

async function createAIWorkflows(urls, options) {
  const results = [];

  for (const url of urls) {
    const workflowData = {
      urls: [url],
      navigationMode: "agentic-navigation",
      userPrompt: options.prompt,
      name: `${options.namePrefix} - ${url}`,
      entity: options.entity,
      fields: options.fields,
      interval: options.interval || "DAILY",
    };

    try {
      const response = await fetch("https://api.kadoa.com/v4/workflows", {
        method: "POST",
        headers: {
          "x-api-key": API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(workflowData),
      });

      const result = await response.json();
      
      if (response.ok) {
        console.log(`✅ ${url}: ${result.workflowId}`);
        results.push({ url, workflowId: result.workflowId });
      } else {
        console.log(`❌ ${url}: ${result.error}`);
        results.push({ url, error: result.error });
      }
    } catch (error) {
      console.log(`❌ ${url}: ${error.message}`);
      results.push({ url, error: error.message });
    }
  }

  return results;
}

// Create workflows for multiple job sites
const jobSites = [
  "https://company1.com/careers",
  "https://company2.com/jobs", 
  "https://company3.com/openings"
];

const workflows = await createAIWorkflows(jobSites, {
  prompt: "Navigate to job listings and extract all open positions",
  namePrefix: "Job Monitor",
  entity: "Jobs",
  fields: [
    { name: "title", dataType: "STRING", description: "Job title", example: "Senior Software Engineer" },
    { name: "location", dataType: "STRING", description: "Job location", example: "San Francisco, CA" },
    { name: "department", dataType: "STRING", description: "Department", example: "Engineering" },
  ],
  interval: "DAILY",
});

console.log(workflows);

​
Advanced Configuration

​
Scheduling Options

Configure when your workflow runs: 
{
  "interval": "CUSTOM",
  "schedules": ["0 9 * * MON-FRI", "0 18 * * MON-FRI"]
}
Available intervals:
  • ONLY_ONCE - Run once
  • HOURLY, DAILY, WEEKLY, MONTHLY - Standard intervals
  • REAL_TIME - Continuous monitoring (Enterprise only)
  • CUSTOM - Use cron expressions

​
Proxy Locations

Specify a geographic location for scraping: 
{
  "location": {
    "type": "manual",
    "isoCode": "US"
  }
}