> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getclaro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Workflows

> Run agentic generation and FindAll discovery workflows.

<Note>
  Authenticate every request with `Authorization: Bearer clr_live_YOUR_API_KEY`.
</Note>

## Start an agentic list

<Badge color="blue">POST</Badge> `/generate/list`

Start an agentic list through the Claro Public API.

**Required scope:** `generate`

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "prompt": "Find European ecommerce software suppliers",
  "min_rows": 10,
  "search_tier": "focus"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/generate/list" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "prompt": "Find European ecommerce software suppliers",
    "min_rows": 10,
    "search_tier": "focus"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/generate/list"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "prompt": "Find European ecommerce software suppliers",
    "min_rows": 10,
    "search_tier": "focus"
  }''')
  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/list`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "prompt": "Find European ecommerce software suppliers",
      "min_rows": 10,
      "search_tier": "focus"
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Generate criteria

<Badge color="blue">POST</Badge> `/generate/criteria`

Generate criteria through the Claro Public API.

**Required scope:** `generate`

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "prompt": "Find sustainable packaging suppliers"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/generate/criteria" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "prompt": "Find sustainable packaging suppliers"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/generate/criteria"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "prompt": "Find sustainable packaging suppliers"
  }''')
  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/criteria`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "prompt": "Find sustainable packaging suppliers"
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Clarify a prompt

<Badge color="blue">POST</Badge> `/generate/clarify-prompt`

Clarify a prompt through the Claro Public API.

**Required scope:** `generate`

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "prompt": "Find software suppliers for an ecommerce company"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/generate/clarify-prompt" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "prompt": "Find software suppliers for an ecommerce company"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/generate/clarify-prompt"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "prompt": "Find software suppliers for an ecommerce company"
  }''')
  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/clarify-prompt`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "prompt": "Find software suppliers for an ecommerce company"
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Generate company details

<Badge color="blue">POST</Badge> `/generate/company-details`

Generate company details through the Claro Public API.

**Required scope:** `generate`

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "company_name": "Claro",
  "domain": "getclaro.ai",
  "functional_area": "Procurement",
  "sub_category": "Supplier intelligence"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/generate/company-details" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "company_name": "Claro",
    "domain": "getclaro.ai",
    "functional_area": "Procurement",
    "sub_category": "Supplier intelligence"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/generate/company-details"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "company_name": "Claro",
    "domain": "getclaro.ai",
    "functional_area": "Procurement",
    "sub_category": "Supplier intelligence"
  }''')
  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/company-details`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "company_name": "Claro",
      "domain": "getclaro.ai",
      "functional_area": "Procurement",
      "sub_category": "Supplier intelligence"
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Ingest FindAll data

<Badge color="blue">POST</Badge> `/generate/find-all/ingest`

Ingest FindAll data through the Claro Public API.

**Required scope:** `generate`

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "objective": "Find UK manufacturers of recycled cardboard packaging"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/generate/find-all/ingest" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "objective": "Find UK manufacturers of recycled cardboard packaging"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/generate/find-all/ingest"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "objective": "Find UK manufacturers of recycled cardboard packaging"
  }''')
  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/find-all/ingest`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "objective": "Find UK manufacturers of recycled cardboard packaging"
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Create FindAll run

<Badge color="blue">POST</Badge> `/generate/find-all/runs`

Create FindAll run through the Claro Public API.

**Required scope:** `generate`

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "objective": "Find UK recycled-packaging manufacturers",
  "entity_type": "company",
  "match_conditions": [
    {
      "name": "Material",
      "description": "Produces recycled cardboard packaging"
    }
  ],
  "match_limit": 10
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/generate/find-all/runs" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "objective": "Find UK recycled-packaging manufacturers",
    "entity_type": "company",
    "match_conditions": [
      {
        "name": "Material",
        "description": "Produces recycled cardboard packaging"
      }
    ],
    "match_limit": 10
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/generate/find-all/runs"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "objective": "Find UK recycled-packaging manufacturers",
    "entity_type": "company",
    "match_conditions": [
      {
        "name": "Material",
        "description": "Produces recycled cardboard packaging"
      }
    ],
    "match_limit": 10
  }''')
  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/find-all/runs`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "objective": "Find UK recycled-packaging manufacturers",
      "entity_type": "company",
      "match_conditions": [
        {
          "name": "Material",
          "description": "Produces recycled cardboard packaging"
        }
      ],
      "match_limit": 10
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `201` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Get FindAll run

<Badge color="green">GET</Badge> `/generate/find-all/runs/{findallId}`

Get FindAll run through the Claro Public API.

**Required scope:** `generate`

### Parameters

| Name        | Location | Type   | Required |
| ----------- | -------- | ------ | -------- |
| `findallId` | path     | string | Yes      |

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/$FINDALL_ID" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests
  findall_id = "YOUR_FINDALL_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/{findall_id}"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  response = requests.get(url, headers=headers)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const findallId = "YOUR_FINDALL_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/${findallId}`, {
    method: "GET",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
    },
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Get FindAll result

<Badge color="green">GET</Badge> `/generate/find-all/runs/{findallId}/result`

Get FindAll result through the Claro Public API.

**Required scope:** `generate`

### Parameters

| Name        | Location | Type   | Required |
| ----------- | -------- | ------ | -------- |
| `findallId` | path     | string | Yes      |

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/$FINDALL_ID/result" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests
  findall_id = "YOUR_FINDALL_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/{findall_id}/result"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  response = requests.get(url, headers=headers)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const findallId = "YOUR_FINDALL_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/${findallId}/result`, {
    method: "GET",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
    },
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Extend FindAll run

<Badge color="blue">POST</Badge> `/generate/find-all/runs/{findallId}/extend`

Extend FindAll run through the Claro Public API.

**Required scope:** `generate`

### Parameters

| Name        | Location | Type   | Required |
| ----------- | -------- | ------ | -------- |
| `findallId` | path     | string | Yes      |

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "additional_match_limit": 10
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/$FINDALL_ID/extend" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "additional_match_limit": 10
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  findall_id = "YOUR_FINDALL_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/{findall_id}/extend"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "additional_match_limit": 10
  }''')
  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const findallId = "YOUR_FINDALL_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/${findallId}/extend`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "additional_match_limit": 10
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Enrich FindAll run

<Badge color="blue">POST</Badge> `/generate/find-all/runs/{findallId}/enrich`

Enrich FindAll run through the Claro Public API.

**Required scope:** `generate`

### Parameters

| Name        | Location | Type   | Required |
| ----------- | -------- | ------ | -------- |
| `findallId` | path     | string | Yes      |

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "output_schema": {
    "employee_count": {
      "type": "number"
    }
  },
  "processor": "company_research"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/$FINDALL_ID/enrich" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "output_schema": {
      "employee_count": {
        "type": "number"
      }
    },
    "processor": "company_research"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  findall_id = "YOUR_FINDALL_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/{findall_id}/enrich"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "output_schema": {
      "employee_count": {
        "type": "number"
      }
    },
    "processor": "company_research"
  }''')
  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const findallId = "YOUR_FINDALL_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/${findallId}/enrich`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "output_schema": {
        "employee_count": {
          "type": "number"
        }
      },
      "processor": "company_research"
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.

***

## Cancel FindAll run

<Badge color="blue">POST</Badge> `/generate/find-all/runs/{findallId}/cancel`

Cancel FindAll run through the Claro Public API.

**Required scope:** `generate`

### Parameters

| Name        | Location | Type   | Required |
| ----------- | -------- | ------ | -------- |
| `findallId` | path     | string | Yes      |

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/$FINDALL_ID/cancel" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests
  findall_id = "YOUR_FINDALL_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/{findall_id}/cancel"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  response = requests.post(url, headers=headers)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const findallId = "YOUR_FINDALL_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/generate/find-all/runs/${findallId}/cancel`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
    },
  });

  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  ```
</CodeGroup>

### Responses

* `200` - Successful response
* `Default` - Error response. Rate-limited responses use HTTP 429.