# Kadoa — how to use (mcp.ai)

Connect your Kadoa account and use 77 tools for web scraping straight from your AI agent. Connect with your own API key. Kadoa is an API-first platform that enables users to create, manage, and monitor data extraction workflows from unstructured data sources.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_kadoa?ms=1787295900000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `kadoa_approve_bulk_validation_rules`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/kadoa`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/kadoa/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/kadoa/approve/bulk/validation/rules` — Tool to bulk approve preview validation rules for a workflow. Use after generating validation rules to activate multiple rules at once.
  - body: { ruleIds: string[], workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/create/crawl/config` — Tool to create a new crawling configuration in Kadoa. Use when you need to configure a custom crawl with specific options like navigation settings, extraction rules, or artifact capture preferences.
  - body: { url?: string, jobId?: string, dataKey?: string, rawMode?: boolean, timeout?: integer, maxDepth?: integer, maxPages?: integer, safeMode?: boolean, blueprint?: object[], proxyType?: string, startUrls?: string[], loadImages?: boolean, maxMatches?: integer, callbackUrl?: string, concurrency?: integer, crawlMethod?: object, proxyCountry?: string, strictDomain?: boolean, billingSource?: string, outputOptions?: object, pathsFilterIn?: string[], matchThreshold?: number, pathsFilterOut?: string[], artifactOptions?: object, extractionOptions?: object, navigationOptions?: object, processDuringCrawl?: boolean }
- `POST https://api.mcp.ai/api/kadoa/create/notification/channel` — Tool to create a notification channel for alerts delivery.
  - body: { name: string, config: object, channelType: string }
- `POST https://api.mcp.ai/api/kadoa/create/schema` — Create a new data schema with specified fields and entity type. Use this tool to define a reusable schema for data extraction workflows. Schemas can have Data Fields (typed data like STRING, NUMBER), 
  - body: { name: string, entity: string, fields: object[] }
- `POST https://api.mcp.ai/api/kadoa/create/support/issue` — Tool to create a support ticket in Kadoa. Use when you need to report bugs, request features, or get help with workflows or integrations. User information is automatically inferred from the authentica
  - body: { files?: string[], title: string, category: string, priority?: integer, workflowId?: string, description: string, subcategory?: string }
- `POST https://api.mcp.ai/api/kadoa/create/workflow/trigger` — Tool to create a trigger that fires when a source workflow emits an event. Use when you need to chain workflows together, triggering one workflow based on events from another. Common use case: trigger
  - body: { enabled?: boolean, eventType: string, workflowId: string, targetWorkflowId: string }
- `POST https://api.mcp.ai/api/kadoa/delete/all/validation/rules` — Tool to soft-delete all validation rules for a specific workflow with optional audit trail. This is a bulk operation that marks rules as deleted without permanently removing them. Use when reconfiguri
  - body: { reason?: string, workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/delete/crawl/config` — Tool to delete a crawling configuration by its config ID. Use when you need to remove an existing crawl configuration.
  - body: { configId: string }
- `POST https://api.mcp.ai/api/kadoa/delete/notification/channel` — Tool to delete a notification channel by its ID. Use when you need to remove a channel that is no longer needed.
  - body: { channel_id: string }
- `POST https://api.mcp.ai/api/kadoa/delete/schema` — Tool to delete a schema and all its revisions. Use when you need to permanently remove a schema from your Kadoa account. This operation cannot be undone.
  - body: { schemaId: string }
- `POST https://api.mcp.ai/api/kadoa/delete/validation/rule` — Tool to delete a validation rule from a Kadoa workflow. Performs a soft delete with optional audit reason.
  - body: { reason?: string, ruleId: string, workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/delete/validation/rules/bulk` — Tool to bulk delete multiple validation rules for a workflow. Use when you need to remove multiple rules at once instead of deleting them individually.
  - body: { reason?: string, ruleIds: string[], workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/delete/workflow` — Delete a workflow permanently from your Kadoa account. Use this tool when you need to permanently remove a workflow. This action cannot be undone.
  - body: { workflow_id: string }
- `POST https://api.mcp.ai/api/kadoa/delete/workflow/trigger` — Tool to delete a trigger from a Kadoa workflow. Use when you need to remove a specific trigger configuration. This action cannot be undone.
  - body: { trigger_id: string, workflow_id: string }
- `POST https://api.mcp.ai/api/kadoa/disable/validation/rule` — Tool to disable a validation rule with a mandatory reason. Use when you need to temporarily or permanently deactivate a data validation rule.
  - body: { reason: string, ruleId: string }
- `POST https://api.mcp.ai/api/kadoa/enable/data/validation` — Tool to enable data validation on a specified workflow. Use after creating or updating a workflow to enforce its validation rules.
  - body: { workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/execute/bulk/workflow/operations` — Execute actions on multiple workflows at once. Use when you need to perform the same operation on many workflows efficiently. Best-effort processing: each workflow is processed independently, so some 
  - body: { action: string, params?: object, workflowIds: string[] }
- `POST https://api.mcp.ai/api/kadoa/export/activity` — Tool to export activity events from audit logs to CSV format for compliance and audit purposes. Use when you need to retrieve historical activity data, generate audit reports, or track user actions ac
  - body: { limit?: integer, offset?: integer, userId?: string, endDate?: string, startDate?: string, eventTypes?: string, interfaces?: string, workflowId?: string, relativeTime?: string, resourceTypes?: string }
- `POST https://api.mcp.ai/api/kadoa/export/activity/workflows` — Tool to export workflow configurations and metadata as CSV for portfolio reviews and compliance reporting. Use when you need to generate compliance reports or review workflow activity across a specifi
  - body: { timeFilter?: string }
- `POST https://api.mcp.ai/api/kadoa/fetch/workflow/configuration` — Retrieve detailed configuration of a workflow by its ID. Returns workflow metadata, extraction schema, scheduling settings, data validation config, and run status. Use this to inspect a workflow's set
  - body: { workflow_id: string }
- `POST https://api.mcp.ai/api/kadoa/get/all/locations` — Retrieves all available scraping proxy locations (countries) supported by Kadoa. Returns ISO country codes (e.g., US, GB, DE) that can be used when configuring workflows to scrape from specific geogra
- `POST https://api.mcp.ai/api/kadoa/get/crawl/bucket/data` — Tool to retrieve file content from the Kadoa crawling bucket (HTML or screenshot). Use when you need to access raw files stored during a crawl session.
  - body: { filenameb64: string }
- `POST https://api.mcp.ai/api/kadoa/get/crawl/config` — Tool to retrieve a crawling configuration by its ID. Use when you need to view the detailed settings of an existing crawl configuration.
  - body: { configId: string }
- `POST https://api.mcp.ai/api/kadoa/get/crawl/status` — Tool to fetch current status of a crawling session. Use when you need to check progress of a crawl by its session ID.
  - body: { session_id: string }
- `POST https://api.mcp.ai/api/kadoa/get/crawled/page/content` — Tool to retrieve content of a crawled page. Use when you need the HTML or Markdown of a page from a specific crawling session.
  - body: { format?: string, pageId: string, sessionId: string }
- `POST https://api.mcp.ai/api/kadoa/get/crawled/pages` — Tool to list pages crawled during a session. Use when you need to paginate through results after starting a crawl session.
  - body: { pageSize?: integer, sessionId: string, currentPage?: integer }
- `POST https://api.mcp.ai/api/kadoa/get/event/type` — Tool to retrieve details for a specific notification event type. Use when you need to understand the schema, description, or configuration of a particular event type for setting up notifications.
  - body: { eventType: string }
- `POST https://api.mcp.ai/api/kadoa/get/event/types` — Tool to retrieve supported notification event types. Use when you need to enumerate available notification triggers.
- `POST https://api.mcp.ai/api/kadoa/get/latest/workflow/data` — Retrieves the extracted data from a Kadoa workflow's most recent run (or a specific run if runId is provided). Returns paginated records in JSON or CSV format. Use Get Workflows action first to obtain
  - body: { gzip?: boolean, page?: integer, limit?: integer, order?: string, runId?: string, format?: string, sortBy?: string, filters?: object[], workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/get/latest/workflow/validation` — Retrieves the latest validation results for the most recent job of a workflow. Returns comprehensive validation data including anomaly counts, detailed anomaly lists by rule, schema issues, and change
  - body: { workflowId: string, includeDryRun?: boolean }
- `POST https://api.mcp.ai/api/kadoa/get/notification/channel` — Tool to retrieve details of a specific notification channel. Use when you have a channel's ID and need its configuration.
  - body: { channel_id: string }
- `POST https://api.mcp.ai/api/kadoa/get/notification/logs` — Tool to retrieve notification event logs with optional filtering by workflow, event type, and date range. Use when you need to audit notification delivery, troubleshoot missing notifications, or revie
  - body: { limit?: integer, offset?: integer, endDate?: string, eventType?: string, startDate?: string, workflowId?: string }
- `POST https://api.mcp.ai/api/kadoa/get/notification/setting` — Retrieves a specific notification setting by its unique identifier. Use this tool to fetch details about how notifications are configured for specific events and which channels are linked. Returns the
  - body: { settingsId: string }
- `POST https://api.mcp.ai/api/kadoa/get/schema` — Retrieve a specific schema by its unique identifier. Returns schema metadata, field definitions, and configuration. Use this to inspect available data structures or validate schema configurations for 
  - body: { schemaId: string }
- `POST https://api.mcp.ai/api/kadoa/get/validation/anomalies` — Tool to retrieve all anomalies for a specific validation. Use this when you need to fetch detailed anomaly data detected during a data validation run, grouped by validation rules with pagination suppo
  - body: { page?: integer, pageSize?: integer, validationId: string }
- `POST https://api.mcp.ai/api/kadoa/get/validation/anomalies/by/rule` — Tool to retrieve anomalies for a specific validation rule. Use this to investigate specific rule violations and understand what data failed validation checks.
  - body: { page?: integer, pageSize?: integer, ruleName: string, validationId: string }
- `POST https://api.mcp.ai/api/kadoa/get/validation/config` — Tool to retrieve the data validation configuration for a specific workflow. Use this to check validation status, alerting thresholds, and rule counts before modifying validation settings.
  - body: { workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/get/validation/rule` — Tool to retrieve a specific validation rule by its ID. Use this to inspect rule details including configuration, status, and metadata.
  - body: { ruleId: string, includeDeleted?: boolean|string }
- `POST https://api.mcp.ai/api/kadoa/get/workflow/audit/log` — Retrieve audit log entries for a workflow. Use when you need to track changes and operations performed on a workflow. Returns paginated log entries showing operation type, user information, and change
  - body: { page?: integer, limit?: integer, workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/get/workflow/job` — Tool to retrieve the current status and telemetry information for a specific workflow job. Use when you need to check the execution status, errors, or metadata of a particular job run.
  - body: { jobId: string, workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/get/workflow/run/history` — Tool to fetch workflow run history. Use when you need to retrieve past run records for a workflow after execution.
  - body: { workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/get/workflow/trigger` — Tool to retrieve a specific trigger for a workflow. Use this when you need to inspect trigger details including its configuration and status.
  - body: { triggerId: string, workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/get/workflow/validation/results` — Retrieves the latest validation results for a specific workflow job. Returns validation details including anomalies detected, rules executed, and schema issues. Returns has_results=false if no validat
  - body: { jobId: string, workflowId: string, includeDryRun?: boolean }
- `POST https://api.mcp.ai/api/kadoa/get/workflows` — Retrieve a paginated list of workflows with optional filtering. Use this tool to list all workflows in your Kadoa account. You can filter by: - search: Find workflows by name, URL, or ID - state: Filt
  - body: { skip?: integer, limit?: integer, state?: string, search?: string, monitoring?: boolean }
- `POST https://api.mcp.ai/api/kadoa/get/workspace/details` — Tool to retrieve detailed information about a workspace (user, team, or organization). Use when you need to get workspace metadata including name, type, email, feature flags, and team information.
  - body: { workspaceId: string }
- `POST https://api.mcp.ai/api/kadoa/list/activity` — Tool to retrieve activity events from audit logs with basic filtering and pagination. Use when you need to track workflow events, user actions, or system activities. Supports time-based filtering (abs
  - body: { limit?: integer, offset?: integer, userId?: string, endDate?: string, startDate?: string, eventTypes?: string, interfaces?: string, workflowId?: string, relativeTime?: string, resourceTypes?: string }
- `POST https://api.mcp.ai/api/kadoa/list/changes` — Tool to retrieve all data changes detected across workflows in your Kadoa account. Use this when you need to monitor what data has changed in your workflows over time. You can filter changes by workfl
  - body: { skip?: integer, limit?: integer, endDate?: string, exclude?: string, startDate?: string, workflowIds?: string }
- `POST https://api.mcp.ai/api/kadoa/list/crawl/sessions` — Tool to retrieve a paginated list of crawling sessions with optional filtering. Use when you need to view all crawl sessions or filter by user ID.
  - body: { page?: integer, userId?: string, pageSize?: integer }
- `POST https://api.mcp.ai/api/kadoa/list/job/validations` — Tool to list all validation runs for a specific job with pagination support. Use when you need to retrieve the full validation history for a job, not just the latest result.
  - body: { page?: integer, jobId: string, pageSize?: integer, workflowId: string, includeDryRun?: boolean }
- `POST https://api.mcp.ai/api/kadoa/list/notification/channels` — Tool to retrieve all notification channels configured for the account. Use when you need to list available channels for alerts delivery.
  - body: { workflowId?: string, includeConfigurations?: boolean }
- `POST https://api.mcp.ai/api/kadoa/list/notification/settings` — Tool to retrieve all notification settings, with optional filtering by workflow ID or event type. Use when you need to list configured notifications or check existing settings before creating new ones
  - body: { eventType?: string, workflowId?: string }
- `POST https://api.mcp.ai/api/kadoa/list/schemas` — Tool to retrieve all schemas accessible by the authenticated user. Use this when you need to see available schema definitions or find a specific schema by name or entity type.
- `POST https://api.mcp.ai/api/kadoa/list/support/states` — Tool to retrieve available support issue states. Use when you need to see what states can be assigned to support tickets.
- `POST https://api.mcp.ai/api/kadoa/list/validation/rules` — Tool to list all data validation rules with optional pagination and filtering.
  - body: { page?: integer, status?: string, groupId?: string, pageSize?: integer, workflowId?: string, includeDeleted?: boolean }
- `POST https://api.mcp.ai/api/kadoa/list/workflow/triggers` — Tool to get all triggers where the specified workflow is the source. Use when you need to retrieve the list of triggers associated with a workflow, such as understanding what actions or workflows are 
  - body: { workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/pause/crawl/session` — Tool to pause an active crawling session. Use when you need to temporarily stop a running crawl without terminating it completely.
  - body: { sessionId: string }
- `POST https://api.mcp.ai/api/kadoa/pause/workflow` — Tool to pause a running or scheduled workflow. Use when you need to temporarily stop a workflow from executing. The workflow will remain paused until explicitly resumed or reactivated.
  - body: { workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/post/advanced/workflow` — Tool to create an advanced workflow. Use when you need a valid advanced workflow ID before updating steps.
  - body: { name?: string, limit?: integer }
- `POST https://api.mcp.ai/api/kadoa/post/crawl` — Starts a new web crawling session to crawl and index pages from a website. Use this tool when you need to: - Crawl an entire website or specific sections - Gather page content for extraction or analys
  - body: { url?: string, timeout?: integer, maxDepth?: integer, maxPages?: integer, startUrls?: string[], proxyCountry?: string, strictDomain?: boolean, pathsFilterIn?: string[], pathsFilterOut?: string[] }
- `POST https://api.mcp.ai/api/kadoa/post/notification/setting` — Tool to create a notification setting linking channels to events. Use when subscribing workflows or workspace-level notifications to specific events.
  - body: { enabled?: boolean, eventType: string, channelIds: string[], workflowId?: string, eventConfiguration: object }
- `POST https://api.mcp.ai/api/kadoa/post/notification/test` — Sends a test notification event to verify notification channel configurations are working correctly. Use this tool to test that your notification channels (email, Slack, Teams, webhooks, etc.) are pro
  - body: { eventType: string, workflowId?: string }
- `POST https://api.mcp.ai/api/kadoa/post/webhook/subscription` — Tool to subscribe to specified webhook events. This will create a webhook channel and then create notification settings for the provided events linking that channel.
  - body: { events: string[], webhookUrl: string, workflowId?: string, channelName?: string, webhookHttpMethod: string }
- `POST https://api.mcp.ai/api/kadoa/post/workflow` — Create a new Kadoa web scraping workflow. This tool creates a workflow that can extract structured data from web pages. Provide URLs to scrape, specify a navigation mode, and define the data schema. F
  - body: { name?: string, tags?: string[], urls: string[], limit?: integer, entity?: string, fields?: object[], interval?: string, location?: object, schemaId?: string, autoStart?: boolean, schedules?: string[], monitoring?: object, userPrompt?: string, description?: string, interactions?: object[], bypassPreview?: boolean, navigationMode: string }
- `POST https://api.mcp.ai/api/kadoa/post/workflow/monitoring` — Configure monitoring and scheduling for a Kadoa workflow to detect data changes. This tool allows you to: - Set up recurring workflow runs at specified intervals (daily, hourly, weekly, etc.) - Enable
  - body: { date?: string, schedules?: string[], monitoring?: object, workflowId: string, updateInterval?: string }
- `POST https://api.mcp.ai/api/kadoa/post/workflow/validation/rule` — Generate an AI-powered data validation rule for a Kadoa workflow. This tool uses AI to convert a natural-language description into a SQL-based validation rule that can detect data quality issues in wo
  - body: { jobId?: string, userPrompt: string, workflowId: string, isPreviewRun?: boolean, selectedColumns?: string[] }
- `POST https://api.mcp.ai/api/kadoa/put/notification/channel` — Tool to update an existing notification channel. Use when you need to modify channel details.
  - body: { name: string, config: object, channelId: string, channelType: string }
- `POST https://api.mcp.ai/api/kadoa/resume/crawl/session` — Tool to resume a paused crawling session. Use when you need to restart a crawl that was previously paused or stopped.
  - body: { sessionId: string }
- `POST https://api.mcp.ai/api/kadoa/resume/workflow` — Resumes a paused, preview, or error workflow. Use when you need to activate a workflow that is not currently running. Cannot resume workflows in certain states; check workflow state first using Get Wo
  - body: { workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/run/adhoc/extraction` — Tool to synchronously extract data from a URL using a given template. Use after choosing the schemaId (custom or 'html', 'body', 'markdown').
  - body: { link: string, location?: object, schemaId: string }
- `POST https://api.mcp.ai/api/kadoa/run/workflow` — Tool to trigger a workflow to run immediately. Use when you need to start a workflow execution on demand. Returns a job ID that can be used to track the execution status.
  - body: { limit?: integer, variables?: object, workflowId: string }
- `POST https://api.mcp.ai/api/kadoa/schedule/validation/job` — Tool to schedule a data validation job for a specific workflow job. Use this to trigger validation rules on job data, detect anomalies, and ensure data quality. Supports custom SQL rules, dry-run mode
  - body: { jobId: string, dryRun?: boolean, strategy?: string, usedPrompt?: string, workflowId: string, customRules?: object[], validationId?: string, skipLibraryRules?: boolean, isWorkflowTriggered?: boolean }
- `POST https://api.mcp.ai/api/kadoa/unsubscribe/from/webhook/events` — Unsubscribe from webhook event notifications by deleting a notification setting. Use this tool when you need to: - Remove an existing notification subscription by its settings ID - Stop receiving webh
  - body: { settingsId: string }
- `POST https://api.mcp.ai/api/kadoa/update/notification/settings` — Tool to update existing notification settings for events. Use when modifying notification configurations such as enabled status, event type, event configuration, or linked channels.
  - body: { enabled?: boolean, eventType?: string, channelIds?: string[], settingsId: string, eventConfiguration?: object }
- `POST https://api.mcp.ai/api/kadoa/update/schema` — Tool to update an existing Kadoa schema. Use when you need to modify schema metadata (name, entity) or update the field definitions. At least one of name, entity, or fields must be provided to update 
  - body: { name?: string, entity?: string, fields?: object[], schemaId: string }
- `POST https://api.mcp.ai/api/kadoa/update/validation/config` — Tool to update the complete data validation configuration including alerting settings for a specific workflow. Use this to modify validation status, alert thresholds, and notification preferences.
  - body: { workflowId: string, dataValidation: object }
- `POST https://api.mcp.ai/api/kadoa/update/workflow/metadata` — Tool to update workflow metadata such as name, description, tags, and configuration settings. Use when you need to modify an existing workflow's properties without recreating it.
  - body: { name?: string, tags?: string[], urls?: string[], limit?: integer, entity?: string, schema?: object[], location?: object, maxDepth?: integer, maxPages?: integer, schedules?: string[], monitoring?: object, userPrompt?: string, workflowId: string, description?: string, pathsFilterIn?: string[], additionalData?: object, navigationMode?: string, pathsFilterOut?: string[], updateInterval?: string }
- `POST https://api.mcp.ai/api/kadoa/update/workflow/trigger` — Tool to update trigger properties including event type and enabled status. Use when you need to modify an existing workflow trigger's configuration.
  - body: { enabled?: boolean, eventType?: string, triggerId: string, workflowId: string }

## Example prompts
- "What can I do in Kadoa?"
- "Show me a summary of my Kadoa account"

## More
- Page: https://mcp.ai/kadoa
- Agent spec (llms.txt): https://mcp.ai/kadoa/llms.txt
- Postman collection: https://mcp.ai/kadoa/postman.json