Create a new workflow

Create a workflow from natural-language instructions, an existing schema, an inline schema, raw-data output options, or a published template.

POST /v4/workflows

Create a new workflow

cURL

curl --request POST \
  --url https://api.kadoa.com/v4/workflows \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "urls": [
    "<string>"
  ],
  "templateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "description": "<string>",
  "tags": [
    "<string>"
  ],
  "schedules": [
    "<string>"
  ],
  "timezone": "<string>",
  "bypassPreview": false,
  "additionalData": "<unknown>",
  "interactions": [
    {
      "selector": "<string>",
      "text": "<string>",
      "timeMs": 123,
      "url": "<string>",
      "tagName": "<string>",
      "innerText": "<string>"
    }
  ],
  "limit": 1073741824,
  "templateVersion": 2,
  "userPrompt": "<string>"
}
'

201

{
  "error": false,
  "success": true,
  "workflowId": "<string>",
  "message": "<string>"
}

Authorizations

x-api-key · string · header · required

API key for authentication

Body

application/json

Body

WorkflowFromTemplate

PromptWorkflow

WorkflowWithExistingSchema

WorkflowWithEntityAndFields

Create a workflow by instantiating a published template. Only urls and templateId are required; prompt, schema, frequency, and notifications are inherited from the template version. templateVersion is optional — omit it to use the latest published version.

Example: {"urls": ["https://example.com"], "templateId": "..."}

urls · string<uri>[] · required

Source URLs. Multiple URLs must belong to one website: subdomains and country domains of the same name (acme.com, careers.acme.co.uk) count as one website. Requests that span several websites are rejected with 422 SOURCES_MULTIPLE_SITES; create one workflow per website instead, optionally from a shared template.

Minimum array length: 1

templateId · string<uuid> · required

ID of the template to instantiate.

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

interval · enum<string>

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

Available options: ONLY_ONCE, EVERY_10_MINUTES, EVERY_20_MINUTES, HALF_HOURLY, HOURLY, TWO_HOURLY, THREE_HOURLY, FOUR_HOURLY, SIX_HOURLY, TWELVE_HOURLY, EIGHTEEN_HOURLY, DAILY, TWO_DAY, THREE_DAY, WEEKLY, BIWEEKLY, TRIWEEKLY, FOUR_WEEKS, MONTHLY, CUSTOM

schedules · string[]

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

timezone · string

IANA timezone for cron schedules (e.g. 'America/New_York'). Defaults to UTC. Cron schedules only.

location · Location · object

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

Show child attributes

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

additionalData · any | null

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

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)

BrowserInteraction

WebExtensionInteraction

Show child attributes

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: 1 <= x <= 2147483647

templateVersion · integer

Optional version (integer) of the template to instantiate. Omit to use the latest published version (resolved once at request time). Provide it to pin a specific version.

Required range: x >= 1

userPrompt · string

Workflow-specific instructions added to the selected template prompt. The template prompt remains template-owned and this text survives template updates.

Required string length: 10 - 5000

Response

201

application/json

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