​
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
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 is currently only available for Enterprise customers. Contact sales to upgrade.

​
How AI Navigation Works

With AI Navigation, you provide natural language instructions and our AI agent:
  • Understands your extraction goals
  • Navigates complex websites autonomously
  • Handles dynamic content and interactions
  • Adapts to different page structures

​
AI Navigation with Schema

// 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 →

​
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"
  }
}