> ## Documentation Index > Fetch the complete documentation index at: https://docs.kadoa.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a new workflow > Create a workflow using natural-language instructions, with optional schema guidance for structured extraction. ## OpenAPI ````yaml post /v4/workflows openapi: 3.0.3 info: title: Kadoa API version: 3.0.0 contact: name: Support email: support@kadoa.com servers: - url: https://api.kadoa.com security: [] paths: /v4/workflows: post: tags: - Workflows summary: Create a new workflow description: >- Create a workflow using natural-language instructions, with optional schema guidance for structured extraction. parameters: [] requestBody: description: Body content: application/json: schema: $ref: '#/components/schemas/PublicWorkflowCreateRequest' responses: '201': description: '201' content: application/json: schema: $ref: '#/components/schemas/CreateWorkflowResponse' '400': description: '400' content: application/json: schema: oneOf: - type: object properties: error: type: boolean description: Indicates an error occurred message: type: string description: Error message details: nullable: true description: Additional error details (e.g., validation errors) required: - error - message - $ref: '#/components/schemas/TemplateControlledFieldError' '401': description: '401' content: application/json: schema: type: object properties: error: type: boolean description: Indicates an error occurred message: type: string description: Error message details: nullable: true description: Additional error details (e.g., validation errors) required: - error - message '403': description: '403' content: application/json: schema: type: object properties: error: type: boolean description: Indicates an error occurred message: type: string description: Error message details: nullable: true description: Additional error details (e.g., validation errors) required: - error - message '404': description: '404' content: application/json: schema: type: object properties: error: type: boolean description: Indicates an error occurred message: type: string description: Error message details: nullable: true description: Additional error details (e.g., validation errors) required: - error - message '500': description: '500' content: application/json: schema: type: object properties: error: type: boolean description: Indicates an error occurred message: type: string description: Error message details: nullable: true description: Additional error details (e.g., validation errors) required: - error - message '503': description: '503' content: application/json: schema: type: object properties: error: type: boolean description: Indicates an error occurred message: type: string description: Error message details: nullable: true description: Additional error details (e.g., validation errors) required: - error - message security: - ApiKeyAuth: [] components: schemas: PublicWorkflowCreateRequest: type: object properties: urls: type: array items: type: string format: uri minItems: 1 description: >- List of URLs to scrape. Can be a single URL or multiple URLs to scrape across different pages or domains. name: type: string minLength: 1 description: >- Human-readable name for this workflow (e.g., 'Product Catalog Scraper') description: type: string maxLength: 500 description: >- Detailed description of what this workflow does and why it was created (maximum 500 characters) tags: type: array items: type: string minLength: 2 description: >- Tags for organizing and categorizing workflows (minimum 2 characters per tag) limit: type: integer minimum: 1 nullable: true description: >- Maximum number of items to scrape. Useful for limiting scope during development or cost control. Pass null to clear an existing limit (unlimited). location: $ref: '#/components/schemas/Location' monitoring: $ref: '#/components/schemas/MonitoringConfig' interval: type: string enum: - 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 description: >- How frequently this workflow should run (ONLY_ONCE, HOURLY, DAILY, WEEKLY, etc.) schedules: type: array items: type: string description: >- Cron expressions for custom schedules. Overrides the interval setting for fine-grained control bypassPreview: default: false type: boolean description: >- Skip preview and validation, deploy scraper immediately. Use with caution - set to true only when you're confident the configuration is correct interactions: type: array items: $ref: '#/components/schemas/Interaction' description: >- Browser interactions to perform before scraping (e.g., clicking buttons, filling forms, scrolling). See Interaction schema for available action types dataValidationEnabled: type: boolean description: >- Enable data quality validation. When true, scraped data is validated against the schema and anomalies are detected additionalData: nullable: true description: >- Additional data for the workflow (e.g. IDs from your system to link data) templateId: type: string format: uuid description: >- Optional: ID of the template this workflow was created from. Records provenance only — the template's config is cloned at creation, not synced. templateVersion: readOnly: true description: >- Reserved: only valid in the WorkflowFromTemplate variant. Pairs with templateId to instantiate a specific template version. userPrompt: type: string minLength: 10 maxLength: 5000 description: >- Natural language instructions for the workflow (10-5000 characters). Describe what data to extract and how to navigate the site schemaId: type: string description: 'Optional: Schema ID to use with prompt-driven extraction' entity: type: string minLength: 1 description: 'Optional: Entity name for prompt-driven extraction' fields: type: array items: description: Extraction field schema discriminator: propertyName: fieldType oneOf: - $ref: '#/components/schemas/DataField' - $ref: '#/components/schemas/ClassificationField' description: 'Optional: Additional extraction fields to guide the workflow' required: - urls - userPrompt title: WorkflowCreateRequest description: >- Create a workflow using natural-language instructions. Navigation is handled automatically for new integrations. CreateWorkflowResponse: type: object properties: error: type: boolean enum: - false description: Error flag (always false on success) success: type: boolean description: Success flag workflowId: type: string description: ID of the created workflow message: type: string description: Success message required: - error - success - workflowId - message title: CreateWorkflowResponse description: Response for workflow creation TemplateControlledFieldError: type: object properties: error: type: boolean enum: - true description: Error flag code: type: string enum: - TEMPLATE_CONTROLLED_FIELD description: Stable error code message: type: string description: Human-readable error message templateId: type: string format: uuid description: Template that controls the offending fields fields: type: array items: type: string description: Controlled field names the caller tried to override required: - error - code - message - templateId - fields title: TemplateControlledFieldError Location: type: object properties: type: type: string enum: - auto - manual description: Location type isoCode: type: string description: Country ISO code for manual location required: - type title: Location description: >- Geographic location for scraping. Use 'auto' for automatic detection or 'manual' to specify a country MonitoringConfig: description: Monitoring configuration type: object properties: fields: type: array items: $ref: '#/components/schemas/MonitoredField' minItems: 1 description: Fields to monitor (at least one required) channels: type: array items: nullable: true description: Notification channels conditions: description: Condition group with logical operator and conditions required: - fields title: MonitoringConfig Interaction: oneOf: - $ref: '#/components/schemas/BrowserInteraction' - $ref: '#/components/schemas/WebExtensionInteraction' title: Interaction description: >- Browser interaction definition. Accepts both simple format (with selector, text, url) and complex format from browser extensions DataField: type: object properties: name: type: string pattern: ^[a-zA-Z][a-zA-Z0-9_]*$ description: Field name (e.g., productName, review_count) description: type: string minLength: 1 description: Field description fieldType: default: SCHEMA type: string enum: - SCHEMA example: oneOf: - type: string - type: array items: type: string description: Example value for the field dataType: type: string description: >- Data type of the field. Must be uppercase: STRING, NUMBER, BOOLEAN, DATE, DATETIME, MONEY, IMAGE, LINK, OBJECT, ARRAY enum: - STRING - NUMBER - BOOLEAN - DATE - DATETIME - MONEY - IMAGE - LINK - OBJECT - ARRAY isKey: type: boolean description: >- Marks this field as part of the record's primary key. Key fields define row identity across runs and enable data linking (records with the same key values are treated as the same record over time, used for dedupe and change detection). Set true ONLY when the field is (1) unique per record on the source, (2) stable across runs (does not change for the same logical record), and (3) reliably present (not nullable/missing). Key fields should be scalar STRING, NUMBER, or LINK fields; avoid structured, semantic, boolean, image, and timestamp/date fields as keys. Good candidates: external IDs, SKUs, canonical URLs, posting IDs. Bad candidates: prices, counts, timestamps, free-text titles/descriptions, or anything that can change between runs. Multiple fields may be marked isKey to form a composite key (all parts must hold the same guarantees). If no field satisfies these guarantees, leave isKey unset on every field — data linking will simply be disabled, which is preferable to a wrong key. Choosing a non-stable or non-unique key causes duplicate rows and missed updates. required: - name - description - dataType title: DataField description: >- Extract and structure specific data from web pages with typed values (e.g., product prices, article titles, dates). Use this for actual data you want to capture. ClassificationField: type: object properties: name: type: string pattern: ^[a-zA-Z][a-zA-Z0-9_]*$ description: Field name (e.g., category, product_type) description: type: string minLength: 1 description: Optional field description fieldType: type: string enum: - CLASSIFICATION categories: type: array items: type: object properties: title: type: string description: Short title/label of the category definition: type: string description: Full definition/description of the category required: - title - definition description: List of predefined categories for classification required: - name - fieldType - categories additionalProperties: true title: ClassificationField description: >- Categorize extracted data into predefined labels. Use this when you want the system to classify content into specific categories you define. MonitoredField: type: object properties: fieldName: type: string description: Name of the field to monitor operator: type: string enum: - changed - added - removed description: Change operator isKeyField: type: boolean description: >- Optional explicit schema-key metadata update for this field. Omit to leave workflow schema key flags unchanged. required: - fieldName - operator title: MonitoredField description: Field monitoring configuration BrowserInteraction: type: object properties: type: type: string enum: - CLICK - TYPE - HOVER - SCROLL - WAIT - KEYPRESS - LOAD - SELECT - BACKSPACE - ENTER - TAB - DELETE - GOTO - REFRESH - NAVIGATE_BACK description: Type of interaction selector: type: string description: CSS selector for the target element (required for CLICK, HOVER) text: type: string description: Text to type (required for TYPE) timeMs: type: number description: Time in milliseconds (required for WAIT) url: type: string description: URL to navigate to (required for GOTO) tagName: type: string description: HTML tag name of the element innerText: type: string description: Inner text content of the element required: - type additionalProperties: true title: BrowserInteraction description: >- 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) WebExtensionInteraction: type: object properties: type: type: string description: Type of interaction id: type: string description: Unique interaction ID x: type: number description: X coordinate 'y': type: number description: Y coordinate link: type: string description: Page URL time: type: string description: Timestamp bodyHTMLUrl: type: string description: URL to captured HTML body screenshotUrl: type: string description: URL to captured screenshot target: type: object properties: id: type: string x: type: number 'y': type: number width: type: number height: type: number tagName: type: string html: type: string innerText: type: string description: Target element information key: type: string description: Key value code: type: string description: Key code metaKeys: type: object properties: alt: type: boolean ctrl: type: boolean meta: type: boolean shift: type: boolean description: Modifier keys state required: - type additionalProperties: true title: WebExtensionInteraction description: Web extension interaction in complex format securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication ````