> ## 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.

# Quickstart

> Create your first workflow and get its data from the dashboard, the SDK and API, or your AI tool.

Describe the data you want, and Kadoa's agent builds a workflow that extracts it.

## Before you begin

* A [Kadoa account](https://kadoa.com/signup).
* For the SDK and API only, a team [API key](https://docs.kadoa.com/docs/api-keys.md) from [Settings > General](https://kadoa.com/settings). Only Admins and Owners can create one.

## Create your first workflow

Every interface creates the same workflow, and the agent builds each one. It finds the source, proposes a schema, builds and tests the extraction, and shows you a sample to approve.

**Dashboard**

**1. Describe the data you want**

Open the [Kadoa Dashboard](https://kadoa.com/dashboard) and select **Create your first workflow**. Describe the task in plain language, for example *"Get me all job postings from sandbox.kadoa.com/careers"*. Include a source URL when you have one. The agent can also help find the source.

![The Kadoa workflow setup prompt with a prompt editor and configuration controls](https://mintcdn.com/kadoa/J2BP2lmQhWDWhIB8/images/assistant/setup-prompt.png?fit=max\&auto=format\&n=J2BP2lmQhWDWhIB8\&q=85\&s=702ecd7501448b2c4d7bb3634383a554)

The setup prompt has optional controls:

* **Product type**
  * **Workflow** extracts a dataset once or on a schedule. Pick it for data that changes a few times a day or less, such as prices you check hourly.
  * **Real-time** watches a website continuously and sends each change as it happens. Select at least one notification channel before you start, unless a selected template provides notifications.
* [**Templates**](https://docs.kadoa.com/docs/templates.md) start you with a reusable prompt, schema, data quality rules, notifications, or frequency.
* [**Notifications**](https://docs.kadoa.com/docs/notifications.md) let you choose existing channels or create one without leaving the prompt.
* [**Tags**](https://docs.kadoa.com/docs/workspaces.md) organize the workflow with team tags.
* [**Variables**](https://docs.kadoa.com/docs/workflows/variables.md) insert reusable values into the prompt.

In the prompt, type `@` for notification channels, `#` for tags, and `$` for variables.

**2. Watch it build**

The agent confirms the source, writes the extraction code, and runs a preview. It narrates each step. The result is a deterministic pipeline. It extracts your data the same way on every run, with no fresh AI guess each time.

![The agent working through its setup plan step by step](https://mintcdn.com/kadoa/-Ftl9ZkRcaJ7_J-T/images/assistant/build.png?fit=max\&auto=format\&n=-Ftl9ZkRcaJ7_J-T\&q=85\&s=8b631a86945d123dd98fd3243c4e1c62)

**3. Review the sample**

Check the preview data. Previews are free.

![Preview data generated by the agent, shown as a structured table](https://mintcdn.com/kadoa/-Ftl9ZkRcaJ7_J-T/images/assistant/sample.png?fit=max\&auto=format\&n=-Ftl9ZkRcaJ7_J-T\&q=85\&s=86fff969027223f472aff4fd63ea9875)

> **What if it's not right?**
>
> Tell the agent what to fix, for example *"add a salary field"* or *"pull location from the detail page"*. It reruns the preview. Nothing is charged until you approve. To check every run automatically, add [data quality](https://docs.kadoa.com/docs/data-quality.md) rules.

**4. Approve and go live**

After you approve, the workflow produces the full dataset. Download it, fetch it from code, or deliver every run to Amazon S3, Snowflake, or another tool you use. See [Export data](https://docs.kadoa.com/docs/export-data.md) and [Integrations](https://docs.kadoa.com/docs/destinations/overview.md). Add [scheduling](https://docs.kadoa.com/docs/workflows/scheduling.md), [change detection](https://docs.kadoa.com/docs/change-detection.md), and [notifications](https://docs.kadoa.com/docs/notifications.md) any time.

![A completed workflow showing the full extracted dataset, with download and run controls and the Agent button](https://mintcdn.com/kadoa/-Ftl9ZkRcaJ7_J-T/images/assistant/full-run.png?fit=max\&auto=format\&n=-Ftl9ZkRcaJ7_J-T\&q=85\&s=3789e0b2f797cf79c3576e0cffd95365)

**5. Refine anytime**

Keep chatting with the agent to change fields, navigation, or the schedule. You can also edit the **Schema**, **Notifications**, and **Tags** panels directly. A template keeps its managed settings read-only until you update or unlink the template.

To build several workflows at once or find sources first, use **Workspace chat**. See [Agent](https://docs.kadoa.com/docs/workflows/agent.md).

**SDK & API**

The SDKs and the REST API create the same workflows you build in the dashboard. Use them to create workflows in bulk, run them from your pipeline, or read data into your systems. The agent still builds each workflow. Your code starts the build and reads the result.

Install the Node.js or Python SDK. The source code is on [GitHub](https://github.com/kadoa-org/kadoa-sdks).

```bash npm theme={null}
npm install @kadoa/node-sdk
```

```bash yarn theme={null}
yarn add @kadoa/node-sdk
```

```bash pnpm theme={null}
pnpm add @kadoa/node-sdk
```

```bash bun theme={null}
bun add @kadoa/node-sdk
```

```bash uv theme={null}
uv add kadoa-sdk
```

```bash pip theme={null}
pip install kadoa-sdk
```

Run your first extraction. To call plain HTTP from any language, use the REST API. See the [API reference](https://docs.kadoa.com/api-reference/introduction.md).

```typescript Node SDK theme={null}
import { KadoaClient } from '@kadoa/node-sdk';

const client = new KadoaClient({
  apiKey: 'YOUR_API_KEY'
});

const result = await client.extraction.run({
  urls: ["https://sandbox.kadoa.com/ecommerce"],
  name: "My First Extraction",
  limit: 10,
});

console.log(result.data);
```

```python Python SDK theme={null}
from kadoa_sdk import ExtractionOptions, KadoaClient, KadoaClientConfig

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

result = client.extraction.run(
    ExtractionOptions(
        urls=["https://sandbox.kadoa.com/ecommerce"],
        name="My First Extraction",
        limit=10,
    )
)

print(result.data)
```

```bash REST API theme={null}
# 1. Create workflow with schema definition
curl -X POST https://api.kadoa.com/v4/workflows \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://sandbox.kadoa.com/ecommerce"],
    "name": "My First Extraction",
    "entity": "Product",
    "fields": [
      {
        "name": "title",
        "dataType": "STRING",
        "description": "Product name"
      },
      {
        "name": "price",
        "dataType": "MONEY",
        "description": "Product price"
      }
    ]
  }'

# Response:
# {
#   "success": true,
#   "workflowId": "507f1f77bcf86cd799439011"
# }

# 2. Check workflow status
curl -X GET https://api.kadoa.com/v4/workflows/507f1f77bcf86cd799439011 \
  -H "x-api-key: YOUR_API_KEY"

# 3. Get the data (once extraction is complete)
curl -X GET https://api.kadoa.com/v4/workflows/507f1f77bcf86cd799439011/data \
  -H "x-api-key: YOUR_API_KEY"
```

The SDK proposes a schema for you. With the REST API, you define the schema yourself.

**MCP**

Connect your AI tool to the [Kadoa MCP server](https://docs.kadoa.com/docs/sdk/mcp.md). Then ask it, for example:

```text theme={null}
> "Extract product names and prices from https://sandbox.kadoa.com/ecommerce"
```

Your AI tool calls `create_workflow`, and the agent builds the workflow. To read the results, ask for the data. Your AI tool calls `fetch_data`.

For the prompt *"Get me all job postings from sandbox.kadoa.com/careers"*, the agent proposes a schema and returns structured data:

```json theme={null}
[
  {
    "title": "Graphic Designer",
    "detailUrl": "https://sandbox.kadoa.com/careers/career/graphic-designer",
    "shortDescription": "Create designs for our digital platforms.",
    "postedDate": "2024-01-15"
  },
  {
    "title": "Data Analyst",
    "detailUrl": "https://sandbox.kadoa.com/careers/career/data-analyst",
    "shortDescription": "Interpret data and analyze results to drive business decisions.",
    "postedDate": "2023-10-20"
  }
]
```

> [!NOTE]
>
> First-time setup may take longer while Kadoa prepares the workflow. Synchronous SDK calls wait up to 30 minutes by default.

To check the legal side, read [Is web scraping allowed?](https://docs.kadoa.com/docs/security/compliance.md)

## Define the fields

To control the output, name each field yourself.

**Dashboard**

If you name the fields in your prompt, for example *"extract title, price, and rating"*, the agent uses exactly those. Otherwise it recommends fields based on the source.

To change the fields later, open the workflow's **Schema** panel. Select **Add field** to add one, or edit an existing field. See [Schemas](https://docs.kadoa.com/docs/workflows/schemas.md) for data types and key fields.

**SDK & API**

```typescript Node SDK theme={null}
const workflow = await client
  .extract({
    urls: ["https://sandbox.kadoa.com/ecommerce"],
    name: "Product Monitor",
    extraction: (builder) =>
      builder
        .entity("Product")
        .field("name", "Product name", "STRING", {
          example: "MacBook Pro",
        })
        .field("price", "Price in USD", "MONEY")
        .field("inStock", "Is available", "BOOLEAN"),
  })
  .create();

const result = await workflow.run({ limit: 10 });
const response = await result.fetchData({});
console.log(response.data);
```

```python Python SDK theme={null}
from kadoa_sdk import (
    ExtractOptions,
    FieldOptions,
    KadoaClient,
    KadoaClientConfig,
    RunWorkflowOptions,
)

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

extract_options = ExtractOptions(
    urls=["https://sandbox.kadoa.com/ecommerce"],
    name="Product Monitor",
    extraction=lambda builder: builder.entity("Product")
    .field("name", "Product name", "STRING", FieldOptions(example="MacBook Pro"))
    .field("price", "Price in USD", "MONEY")
    .field("inStock", "Is available", "BOOLEAN"),
)

workflow = client.extract(extract_options).create()
print(f"Workflow created: {workflow.workflow_id}")

result = workflow.run(RunWorkflowOptions(limit=10))
response = result.fetch_data({})
print(response.data)
```

```javascript REST API theme={null}
// POST https://api.kadoa.com/v4/workflows
{
  "urls": ["https://sandbox.kadoa.com/ecommerce"],
  "name": "Product Monitor",
  "entity": "Product",
  "fields": [
    {
      "name": "name",
      "dataType": "STRING",
      "description": "Product name"
    },
    {
      "name": "price",
      "dataType": "MONEY",
      "description": "Price in USD"
    },
    {
      "name": "inStock",
      "dataType": "BOOLEAN",
      "description": "Is available"
    }
  ]
}
```

**MCP**

Name the fields in your request, for example:

```text theme={null}
> "Extract product name, price in USD, and availability from https://sandbox.kadoa.com/ecommerce"
```

Your AI tool can pass the fields to `create_workflow` as a schema.

## Next steps

> **[Schemas](https://docs.kadoa.com/docs/workflows/schemas.md)**
>
> Customize the fields the agent proposed

> **[Scheduling](https://docs.kadoa.com/docs/workflows/scheduling.md)**
>
> Run the workflow on a schedule

> **[Notifications](https://docs.kadoa.com/docs/notifications.md)**
>
> Route events to email, Slack, webhooks, and WebSockets

> **[Export data](https://docs.kadoa.com/docs/export-data.md)**
>
> Download your data or read it with the SDK and API


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.