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>"
  ],
  "userPrompt": "<string>",
  "name": "<string>",
  "description": "<string>",
  "tags": [
    "<string>"
  ],
  "limit": 2,
  "schedules": [
    "<string>"
  ],
  "bypassPreview": false,
  "interactions": [
    {
      "selector": "<string>",
      "text": "<string>",
      "timeMs": 123,
      "url": "<string>",
      "tagName": "<string>",
      "innerText": "<string>"
    }
  ],
  "dataValidationEnabled": true,
  "additionalData": "<unknown>",
  "templateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "schemaId": "<string>",
  "entity": "<string>",
  "fields": [
    {
      "name": "<string>",
      "description": "<string>",
      "instruction": "<string>",
      "fieldType": "SCHEMA",
      "example": "<string>",
      "shape": "<unknown>",
      "isKey": true
    }
  ]
}
'
import requests

url = "https://api.kadoa.com/v4/workflows"

payload = {
    "urls": ["<string>"],
    "userPrompt": "<string>",
    "name": "<string>",
    "description": "<string>",
    "tags": ["<string>"],
    "limit": 2,
    "schedules": ["<string>"],
    "bypassPreview": False,
    "interactions": [
        {
            "selector": "<string>",
            "text": "<string>",
            "timeMs": 123,
            "url": "<string>",
            "tagName": "<string>",
            "innerText": "<string>"
        }
    ],
    "dataValidationEnabled": True,
    "additionalData": "<unknown>",
    "templateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "schemaId": "<string>",
    "entity": "<string>",
    "fields": [
        {
            "name": "<string>",
            "description": "<string>",
            "instruction": "<string>",
            "fieldType": "SCHEMA",
            "example": "<string>",
            "shape": "<unknown>",
            "isKey": True
        }
    ]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    urls: ['<string>'],
    userPrompt: '<string>',
    name: '<string>',
    description: '<string>',
    tags: ['<string>'],
    limit: 2,
    schedules: ['<string>'],
    bypassPreview: false,
    interactions: [
      {
        selector: '<string>',
        text: '<string>',
        timeMs: 123,
        url: '<string>',
        tagName: '<string>',
        innerText: '<string>'
      }
    ],
    dataValidationEnabled: true,
    additionalData: '<unknown>',
    templateId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    schemaId: '<string>',
    entity: '<string>',
    fields: [
      {
        name: '<string>',
        description: '<string>',
        instruction: '<string>',
        fieldType: 'SCHEMA',
        example: '<string>',
        shape: '<unknown>',
        isKey: true
      }
    ]
  })
};

fetch('https://api.kadoa.com/v4/workflows', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.kadoa.com/v4/workflows",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'urls' => [
        '<string>'
    ],
    'userPrompt' => '<string>',
    'name' => '<string>',
    'description' => '<string>',
    'tags' => [
        '<string>'
    ],
    'limit' => 2,
    'schedules' => [
        '<string>'
    ],
    'bypassPreview' => false,
    'interactions' => [
        [
                'selector' => '<string>',
                'text' => '<string>',
                'timeMs' => 123,
                'url' => '<string>',
                'tagName' => '<string>',
                'innerText' => '<string>'
        ]
    ],
    'dataValidationEnabled' => true,
    'additionalData' => '<unknown>',
    'templateId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'schemaId' => '<string>',
    'entity' => '<string>',
    'fields' => [
        [
                'name' => '<string>',
                'description' => '<string>',
                'instruction' => '<string>',
                'fieldType' => 'SCHEMA',
                'example' => '<string>',
                'shape' => '<unknown>',
                'isKey' => true
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.kadoa.com/v4/workflows"

	payload := strings.NewReader("{\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"userPrompt\": \"<string>\",\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"limit\": 2,\n  \"schedules\": [\n    \"<string>\"\n  ],\n  \"bypassPreview\": false,\n  \"interactions\": [\n    {\n      \"selector\": \"<string>\",\n      \"text\": \"<string>\",\n      \"timeMs\": 123,\n      \"url\": \"<string>\",\n      \"tagName\": \"<string>\",\n      \"innerText\": \"<string>\"\n    }\n  ],\n  \"dataValidationEnabled\": true,\n  \"additionalData\": \"<unknown>\",\n  \"templateId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"schemaId\": \"<string>\",\n  \"entity\": \"<string>\",\n  \"fields\": [\n    {\n      \"name\": \"<string>\",\n      \"description\": \"<string>\",\n      \"instruction\": \"<string>\",\n      \"fieldType\": \"SCHEMA\",\n      \"example\": \"<string>\",\n      \"shape\": \"<unknown>\",\n      \"isKey\": true\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.kadoa.com/v4/workflows")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"userPrompt\": \"<string>\",\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"limit\": 2,\n  \"schedules\": [\n    \"<string>\"\n  ],\n  \"bypassPreview\": false,\n  \"interactions\": [\n    {\n      \"selector\": \"<string>\",\n      \"text\": \"<string>\",\n      \"timeMs\": 123,\n      \"url\": \"<string>\",\n      \"tagName\": \"<string>\",\n      \"innerText\": \"<string>\"\n    }\n  ],\n  \"dataValidationEnabled\": true,\n  \"additionalData\": \"<unknown>\",\n  \"templateId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"schemaId\": \"<string>\",\n  \"entity\": \"<string>\",\n  \"fields\": [\n    {\n      \"name\": \"<string>\",\n      \"description\": \"<string>\",\n      \"instruction\": \"<string>\",\n      \"fieldType\": \"SCHEMA\",\n      \"example\": \"<string>\",\n      \"shape\": \"<unknown>\",\n      \"isKey\": true\n    }\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.kadoa.com/v4/workflows")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"urls\": [\n    \"<string>\"\n  ],\n  \"userPrompt\": \"<string>\",\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"limit\": 2,\n  \"schedules\": [\n    \"<string>\"\n  ],\n  \"bypassPreview\": false,\n  \"interactions\": [\n    {\n      \"selector\": \"<string>\",\n      \"text\": \"<string>\",\n      \"timeMs\": 123,\n      \"url\": \"<string>\",\n      \"tagName\": \"<string>\",\n      \"innerText\": \"<string>\"\n    }\n  ],\n  \"dataValidationEnabled\": true,\n  \"additionalData\": \"<unknown>\",\n  \"templateId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"schemaId\": \"<string>\",\n  \"entity\": \"<string>\",\n  \"fields\": [\n    {\n      \"name\": \"<string>\",\n      \"description\": \"<string>\",\n      \"instruction\": \"<string>\",\n      \"fieldType\": \"SCHEMA\",\n      \"example\": \"<string>\",\n      \"shape\": \"<unknown>\",\n      \"isKey\": true\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "error": false,
  "success": true,
  "workflowId": "<string>",
  "message": "<string>"
}
{
  "error": true,
  "message": "<string>",
  "details": "<unknown>"
}
{
  "error": true,
  "message": "<string>",
  "details": "<unknown>"
}
{
  "error": true,
  "message": "<string>",
  "details": "<unknown>"
}
{
  "error": true,
  "message": "<string>",
  "details": "<unknown>"
}
{
  "error": true,
  "message": "<string>",
  "details": "<unknown>"
}
{
  "error": true,
  "message": "<string>",
  "details": "<unknown>"
}

Authorizations

​
x-api-key
string
header
required

API key for authentication

Body

application/json

Body

Create a workflow using natural-language instructions. Navigation is handled automatically for new integrations.

​
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
​
userPrompt
string
required

Natural language instructions for the workflow (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 2 characters per tag)

Minimum string length: 2
​
limit
integer | null

Maximum number of items to scrape. Useful for limiting scope during development or cost control. Pass null to clear an existing limit (unlimited).

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

​
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)

​
templateId
string<uuid>

Optional: ID of the template this workflow was created from. Records provenance only — the template's config is cloned at creation, not synced.

​
schemaId
string

Optional: Schema ID to use with prompt-driven extraction

​
entity
string

Optional: Entity name for prompt-driven extraction

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

Optional: Additional extraction fields to guide the workflow

Extraction field schema

Response

201

Response for workflow creation

​
error
enum<boolean>
required

Error flag (always false on success)

Available options:
false
​
success
boolean
required

Success flag

​
workflowId
string
required

ID of the created workflow

​
message
string
required

Success message