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

# Knowledge & Taxonomy

> Manage knowledge-base content and taxonomy mapping workflows.

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

## List knowledge base items

<Badge color="green">GET</Badge> `/knowledge-base`

List knowledge base items through the Claro Public API.

**Required scope:** `taxonomy`

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.getclaro.ai/api/public/v1/knowledge-base" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/knowledge-base"
  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 response = await fetch(`https://platform.getclaro.ai/api/public/v1/knowledge-base`, {
    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 knowledge base item

<Badge color="green">GET</Badge> `/knowledge-base/{id}`

Get knowledge base item through the Claro Public API.

**Required scope:** `taxonomy`

### Parameters

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

### Example request

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

  ```python Python theme={null}
  import requests
  id = "YOUR_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/knowledge-base/{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 id = "YOUR_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/knowledge-base/${id}`, {
    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.

***

## Update knowledge base item

<Badge color="orange">PATCH</Badge> `/knowledge-base/{id}`

Update knowledge base item through the Claro Public API.

**Required scope:** `taxonomy`

### Parameters

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

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "name": "Procurement policy",
  "description": "Current purchasing requirements"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://platform.getclaro.ai/api/public/v1/knowledge-base/$ID" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "name": "Procurement policy",
    "description": "Current purchasing requirements"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  id = "YOUR_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/knowledge-base/{id}"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "name": "Procurement policy",
    "description": "Current purchasing requirements"
  }''')
  response = requests.patch(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const id = "YOUR_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/knowledge-base/${id}`, {
    method: "PATCH",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "name": "Procurement policy",
      "description": "Current purchasing requirements"
    }),
  });

  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.

***

## Upload knowledge base files

<Badge color="blue">POST</Badge> `/knowledge-base/upload/files`

Upload knowledge base files through the Claro Public API.

**Required scope:** `taxonomy`

### Request body

Content type: `multipart/form-data` (required)

Upload the source file using the `file` form field.

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/knowledge-base/upload/files" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -F "file=@path/to/file.csv"
  ```

  ```python Python theme={null}
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/knowledge-base/upload/files"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  files = {"file": open("path/to/file.csv", "rb")}
  response = requests.post(url, headers=headers, files=files)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append("file", fileInput.files[0]);

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/knowledge-base/upload/files`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
    },
    body: formData,
  });

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

### Responses

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

***

## Upload knowledge base content

<Badge color="blue">POST</Badge> `/knowledge-base/upload/content`

Upload knowledge base content through the Claro Public API.

**Required scope:** `taxonomy`

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "name": "Procurement policy",
  "description": "Purchasing requirements",
  "content": "All suppliers must complete due diligence."
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/knowledge-base/upload/content" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "name": "Procurement policy",
    "description": "Purchasing requirements",
    "content": "All suppliers must complete due diligence."
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/knowledge-base/upload/content"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "name": "Procurement policy",
    "description": "Purchasing requirements",
    "content": "All suppliers must complete due diligence."
  }''')
  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/knowledge-base/upload/content`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "name": "Procurement policy",
      "description": "Purchasing requirements",
      "content": "All suppliers must complete due diligence."
    }),
  });

  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.

***

## Classify an HTS code

<Badge color="blue">POST</Badge> `/generate/hts-agent`

Classify an HTS code 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/hts-agent" \
    -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/hts-agent"
  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/hts-agent`, {
    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.

***

## Detect taxonomy structure

<Badge color="blue">POST</Badge> `/taxonomy/detect-structure`

Detect taxonomy structure through the Claro Public API.

**Required scope:** `taxonomy`

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "headers": [
    "Department",
    "Category"
  ],
  "rows": [
    {
      "Department": "Electronics",
      "Category": "Laptops"
    }
  ]
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/taxonomy/detect-structure" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "headers": [
      "Department",
      "Category"
    ],
    "rows": [
      {
        "Department": "Electronics",
        "Category": "Laptops"
      }
    ]
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  url = f"https://platform.getclaro.ai/api/public/v1/taxonomy/detect-structure"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "headers": [
      "Department",
      "Category"
    ],
    "rows": [
      {
        "Department": "Electronics",
        "Category": "Laptops"
      }
    ]
  }''')
  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/taxonomy/detect-structure`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "headers": [
        "Department",
        "Category"
      ],
      "rows": [
        {
          "Department": "Electronics",
          "Category": "Laptops"
        }
      ]
    }),
  });

  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.

***

## Map taxonomy

<Badge color="blue">POST</Badge> `/taxonomy/{taxonomyId}/map`

Map taxonomy through the Claro Public API.

**Required scope:** `taxonomy`

### Parameters

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

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "catalogObjectId": "00000000-0000-4000-8000-000000000001"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.getclaro.ai/api/public/v1/taxonomy/$TAXONOMY_ID/map" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "catalogObjectId": "00000000-0000-4000-8000-000000000001"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  taxonomy_id = "YOUR_TAXONOMY_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/taxonomy/{taxonomy_id}/map"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "catalogObjectId": "00000000-0000-4000-8000-000000000001"
  }''')
  response = requests.post(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const taxonomyId = "YOUR_TAXONOMY_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/taxonomy/${taxonomyId}/map`, {
    method: "POST",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "catalogObjectId": "00000000-0000-4000-8000-000000000001"
    }),
  });

  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.

***

## List taxonomy assignments

<Badge color="green">GET</Badge> `/taxonomy/{taxonomyId}/assignments`

List taxonomy assignments through the Claro Public API.

**Required scope:** `taxonomy`

### Parameters

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

### Example request

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

  ```python Python theme={null}
  import requests
  taxonomy_id = "YOUR_TAXONOMY_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/taxonomy/{taxonomy_id}/assignments"
  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 taxonomyId = "YOUR_TAXONOMY_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/taxonomy/${taxonomyId}/assignments`, {
    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.

***

## Review taxonomy assignment

<Badge color="orange">PATCH</Badge> `/taxonomy/assignments/{id}`

Review taxonomy assignment through the Claro Public API.

**Required scope:** `taxonomy`

### Parameters

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

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "reviewStatus": "ACCEPTED"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://platform.getclaro.ai/api/public/v1/taxonomy/assignments/$ID" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "reviewStatus": "ACCEPTED"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  id = "YOUR_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/taxonomy/assignments/{id}"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "reviewStatus": "ACCEPTED"
  }''')
  response = requests.patch(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const id = "YOUR_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/taxonomy/assignments/${id}`, {
    method: "PATCH",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "reviewStatus": "ACCEPTED"
    }),
  });

  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.

***

## Reassign taxonomy assignment

<Badge color="orange">PATCH</Badge> `/taxonomy/assignments/{id}/reassign`

Reassign taxonomy assignment through the Claro Public API.

**Required scope:** `taxonomy`

### Parameters

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

### Request body

Content type: `application/json` (required)

```json Request example theme={null}
{
  "categoryRowId": "00000000-0000-4000-8000-000000000008"
}
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://platform.getclaro.ai/api/public/v1/taxonomy/assignments/$ID/reassign" \
    -H "Authorization: Bearer clr_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "categoryRowId": "00000000-0000-4000-8000-000000000008"
  }'
  ```

  ```python Python theme={null}
  import json
  import requests
  id = "YOUR_ID"
  url = f"https://platform.getclaro.ai/api/public/v1/taxonomy/assignments/{id}/reassign"
  headers = {"Authorization": "Bearer clr_live_YOUR_API_KEY"}
  payload = json.loads(r'''{
    "categoryRowId": "00000000-0000-4000-8000-000000000008"
  }''')
  response = requests.patch(url, headers=headers, json=payload)
  response.raise_for_status()
  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const id = "YOUR_ID";

  const response = await fetch(`https://platform.getclaro.ai/api/public/v1/taxonomy/assignments/${id}/reassign`, {
    method: "PATCH",
    headers: {
      Authorization: "Bearer clr_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "categoryRowId": "00000000-0000-4000-8000-000000000008"
    }),
  });

  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.