Skip to main content
POST
/
v4
/
workflows
Create a new workflow
curl --request POST \
  --url https://api.kadoa.com/v4/workflows/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "urls": [
    "<string>"
  ],
  "navigationMode": "agentic-navigation",
  "userPrompt": "<string>",
  "name": "<string>",
  "description": "<string>",
  "tags": [
    "<string>"
  ],
  "limit": 2,
  "location": {
    "type": "auto",
    "isoCode": "<string>"
  },
  "monitoring": {
    "enabled": true,
    "fields": [],
    "channels": [
      "<unknown>"
    ],
    "conditions": "<unknown>"
  },
  "interval": "ONLY_ONCE",
  "schedules": [
    "<string>"
  ],
  "bypassPreview": false,
  "autoStart": true,
  "interactions": [
    {
      "type": "CLICK",
      "selector": "<string>",
      "text": "<string>",
      "timeMs": 123,
      "url": "<string>",
      "tagName": "<string>",
      "innerText": "<string>"
    }
  ],
  "dataValidationEnabled": true,
  "additionalData": "<unknown>",
  "maxPages": 50000,
  "maxDepth": 100,
  "pathsFilterIn": [
    "<string>"
  ],
  "pathsFilterOut": [
    "<string>"
  ],
  "schemaId": "<string>",
  "entity": "<string>",
  "fields": [
    {
      "name": "<string>",
      "description": "<string>",
      "dataType": "STRING",
      "fieldType": "SCHEMA",
      "example": "<string>",
      "isKey": true
    }
  ]
}
'
{
  "error": false,
  "success": true,
  "workflowId": "<string>",
  "message": "<string>"
}

Authorizations

​
x-api-key
string
header
required

API key for authentication

Body

application/json

Body

Create an AI-powered workflow that uses natural language instructions to intelligently extract and adapt data extraction based on page content. The agent can navigate complex sites and understand context.

Example: {"urls": ["https://example.com"], "navigationMode": "agentic-navigation", "userPrompt": "Extract all job listings with title, company, salary, and location. Click on each listing to get full details."}

​
urls
string<uri>[]
required

List of URLs to scrape. Can be a single URL or multiple URLs to scrape across different pages or domains.

Minimum array length: 1
​
navigationMode
enum<string>
required

Must be set to 'agentic-navigation' for agentic workflows

Available options:
agentic-navigation
​
userPrompt
string
required

Natural language instructions for the AI agent (10-5000 characters). Describe what data to extract and how to navigate the site

Required string length: 10 - 5000
​
name
string

Human-readable name for this workflow (e.g., 'Product Catalog Scraper')

Minimum string length: 1
​
description
string

Detailed description of what this workflow does and why it was created (maximum 500 characters)

Maximum string length: 500
​
tags
string[]

Tags for organizing and categorizing workflows (minimum 3 characters per tag)

Minimum string length: 3
​
limit
integer

Maximum number of items to scrape. Useful for limiting scope during development or cost control

Required range: x >= 1
​
location
Location · object

Geographic location for scraping. Use 'auto' for automatic detection or 'manual' to specify a country

​
monitoring
MonitoringConfig · object

Monitoring configuration

​
interval
enum<string>

How frequently this workflow should run (ONLY_ONCE, HOURLY, DAILY, WEEKLY, etc.)

Available options:
ONLY_ONCE,
EVERY_10_MINUTES,
HALF_HOURLY,
HOURLY,
THREE_HOURLY,
SIX_HOURLY,
TWELVE_HOURLY,
EIGHTEEN_HOURLY,
DAILY,
TWO_DAY,
THREE_DAY,
WEEKLY,
BIWEEKLY,
TRIWEEKLY,
FOUR_WEEKS,
MONTHLY,
REAL_TIME,
CUSTOM
​
schedules
string[]

Cron expressions for custom schedules. Overrides the interval setting for fine-grained control

​
bypassPreview
boolean
default:false

Skip preview and validation, deploy scraper immediately. Use with caution - set to true only when you're confident the configuration is correct

​
autoStart
boolean
default:true

Automatically start the workflow after creation. Set to false if you want to test/review before starting

​
interactions
(BrowserInteraction · object | WebExtensionInteraction · object)[]

Browser interactions to perform before scraping (e.g., clicking buttons, filling forms, scrolling). See Interaction schema for available action types

Browser interaction definition. Examples:

  • CLICK: {type: 'CLICK', selector: '#submit-btn'}
  • TYPE: {type: 'TYPE', text: 'hello world'}
  • WAIT: {type: 'WAIT', timeMs: 2000}
  • GOTO: {type: 'GOTO', url: 'https://example.com'}
  • ENTER/TAB/BACKSPACE/DELETE/REFRESH/NAVIGATE_BACK/SCROLL/HOVER/SELECT/LOAD/KEYPRESS: {type: 'ENTER'} (no additional parameters needed)
​
dataValidationEnabled
boolean

Enable data quality validation. When true, scraped data is validated against the schema and anomalies are detected

​
additionalData
any | null

Additional data for the workflow (e.g. IDs from your system to link data)

​
maxPages
integer

Maximum pages to crawl (default: 10,000, max: 100,000). Only used when navigationMode is 'all-pages'

Required range: 1 <= x <= 100000
​
maxDepth
integer

Maximum crawl depth (default: 50, max: 200). Only used when navigationMode is 'all-pages'

Required range: 1 <= x <= 200
​
pathsFilterIn
string[]

Regex patterns to include specific paths during crawling. Only used when navigationMode is 'all-pages'

​
pathsFilterOut
string[]

Regex patterns to exclude specific paths during crawling. Only used when navigationMode is 'all-pages'

​
schemaId
string

Optional: Schema ID to use with agentic extraction

​
entity
string

Optional: Entity name for agentic extraction

Minimum string length: 1
​
fields
(DataField · object | RawContentField · object | ClassificationField · object)[]

Optional: Additional extraction fields to guide the agent

Extraction field schema

Response

201

Response for workflow creation

​
error
enum<boolean>
required

Error flag (always false on success)

Available options:
true,
false
​
success
boolean
required

Success flag

​
workflowId
string
required

ID of the created workflow

​
message
string
required

Success message