Version: 1.3.3

LOR API Documentation

Directory APIs

Root Directory Retrieval Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v1/directory/root
Summary: Gets the root directory for the current tenant.

Description

Returns the root directory information for a tenant if it exists.

Request

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	string	UUIDs	optional

Response

{
  "status_code": "200",
  "message": "Root directory found",
  "data": [{
    "name": "root_ABC12",
    "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "type": "Folder",
    "is_private": false,
    "custom_metadata": {}
  }]
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v1/directory/root"
token = "YOUR_TOKEN"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)
print(response.json())

Root Directory Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/directory/root
Summary: Creates a root directory for a tenant.

Description

Creates a root directory for a tenant. The root directory will be named as root_{tenant_code}.

Request

Query Parameters

Parameter	Description	Data Type	Allowed Values	Required
ext_user_id_ref	External user ID reference	string	UUIDs	optional

Payload

Field	Type	Description	Validation
tenant_code	string	Tenant identifier	5 character alphanumeric code

Response

{
  "status_code": "201",
  "message": "Successfully created root directory"
}

Other Responses
- 409 Conflict: Can't create duplicate root directory

Usage

import requests

url = "https://api.kadal.ai/cl/api/v1/directory/root"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "tenant_code": "ABC12"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Directory Retrieval Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v1/directory/{folder_id}
Summary: Gets information about a specific directory.

Description

Gets folder information for a specific directory and shows information for all children present inside the requested directory.

Request

Query Parameters
- folder_id (path): UUID of the directory to retrieve
- sorting_by (query, optional): Sort result by title or modified_date (default: updated_at)
- order (query, optional): Sort order (asc/desc, default: asc)
- ext_user_id_ref (query, optional): External user ID reference

Response

{
  "status_code": "200",
  "message": "Child directory found.",
  "data": [{
    "name": "Directory Name",
    "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "type": "Folder",
    "is_private": false,
    "custom_metadata": {},
    "children": []
  }]
}

Directory Metadata Update Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v1/directory/{folder_id}
Summary: Updates metadata of a directory.

Description

Updates metadata of a directory that is other than a root directory. All fields are optional for update, but at least one field should be provided.

Request

Query Parameters
- folder_id (path): UUID of the directory to update
- ext_user_id_ref (query, optional): External user ID reference
Payload

{
  "name": "Updated Name",
  "is_private": true,
  "type": "Folder",
  "custom_metadata": {
    "kvp": {},
    "tags": [],
    "taxonomy": []
  }
}

Response

{
  "status_code": "200",
  "message": "Successfully updated child directory"
}

Usage

import requests

folder_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/directory/root/children/{folder_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "name": "Updated Folder",
    "is_private": True,
    "type": "Module",
    "custom_metadata": {
        "kvp": {"key1": "updated_value"},
        "tags": ["new_tag"],
        "taxonomy": [{"uuid": "new_value", "title": "new_title"}]
    }
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

Child Directories Addition Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/directory/{folder_id}
Summary: Adds directories to an existing directory.

Description

Adds one or more directories to a parent directory. The parent directory can be a root directory or any other existing directory.

Request

Query Parameters
- folder_id: UUID of the parent directory
- ext_user_id_ref (optional): External user ID reference
Payload

{
  "directory_structure": [{
    "name": "New Directory",
    "is_private": false,
    "type": "Folder",
    "custom_metadata": {
      "kvp": {},
      "tags": [],
      "taxonomy": []
    },
    "children": []
  }]
}

Response

{
  "status_code": "201",
  "message": "Successfully added directories"
}

Other Responses
- 206 Partial Content: Some directories added successfully

Usage

import requests

folder_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/directory/root/children/{folder_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "directory_structure": [{
        "name": "Folder 1",
        "is_private": False,
        "type": "Folder",
        "children": [],
        "custom_metadata": {
            "kvp": {"key1": "value1"},
            "tags": ["tag1"],
            "taxonomy": [{"uuid": "value1", "title": "value2"}]
        }
    }]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Directory Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v1/directory/{folder_id}
Summary: Deletes a directory and its contents.

Description

Deletes a directory that is other than a root directory and all its underlying directories.

Request

Query Parameters
- folder_id (path): UUID of the directory to delete
- ext_user_id_ref (query, optional): External user ID reference

Response

{
  "status_code": "200",
  "message": "Successfully deleted directory"
}

Usage

import requests

token = "YOUR_TOKEN"
folder_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/directory/root/children/{folder_id}"
headers = {
    "Authorization": f"Bearer <token>"
}

response = requests.delete(url, headers=headers)
print(response.json())

Bulk Directory Retrieval Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v1/directory/details/bulk
Summary: Gets information about multiple directories.

Description

Gets folder information for multiple folders and shows information for all children present inside each requested directory.

Request

Query Parameters
- ext_user_id_ref (optional): External user ID reference
Payload

{
  "folder_ids": [
    "1ea3d628-f555-41c7-8101-c56a65087bab",
    "2fb4d839-g666-52d8-9212-d67b76198bac"
  ]
}

Response

{
  "status_code": "200",
  "message": "Directories found",
  "data": [{
    "name": "Directory Name",
    "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "type": "Folder",
    "is_private": false,
    "custom_metadata": {},
    "children": []
  }]
}

Directory Search Endpoint

Method: POST
Path: https://api.kadal.ai//cl/api/v1/directory/aggregate/details
Summary: Searches for directories based on a query string.

Description

Gets all folder information for a tenant matching the search criteria.

Request

Query Parameters
- query_string (optional): Query string to search for folders
- sort_by (optional): Sorting field (default: updated_at)
- order (optional): Sort order (default: asc)
- page_no (optional): Page number (default: 1)
- page_size (optional): Page size (default: 20)
- ext_user_id_ref (optional): External user ID reference

Response

{
  "status_code": "200",
  "message": "Directories found",
  "data": {
    "total": 50,
    "page": 1,
    "size": 20,
    "results": [{
      "name": "Directory Name",
      "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
      "type": "Folder",
      "is_private": false,
      "custom_metadata": {}
    }]
  }
}

My Folder APIs

My Folder Upsert Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v1/my_folder
Summary: Gets a user's private folder or creates it if it doesn't exist.

Description

Gets the private folder of a user. If the private folder does not exist, it will be created.

Response

{
  "status_code": "200",
  "message": "Successfully retrieved my_folder",
  "my_folder_directory_id": "0ad38b25-f71a-48e5-b649-c912a5350f40"
}

Other Responses
- 404 Not Found: Root directory not found (required to create my_folder)

Notes

The my_folder directory is created as a private folder under the tenant's root directory
The folder has chat_interface_only: true set in its custom metadata
Only the owner can access their my_folder directory

Usage

import requests

url = "https://api.kadal.ai/cl/api/v1/my_folder"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.get(url, headers=headers)
print(response.json())

Objects V2 APIs

Object Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/objects
Summary: Creates a new object in the repository.

Description

Creates a new object in the object repository. The source_category under system_metadata can be KnowledgeBase/Guideline/OutputTemplate.

Request

Payload

Field	Type	Description	Validation
object_id	string	Optional UUID for the object	UUID format
title	string	Object title	Required
description	string	Object description	Optional
system_metadata	object	System metadata	Required
system_metadata.source	string	Source of the object	Required
system_metadata.source_category	string	Category (KnowledgeBase/Guideline/OutputTemplate)	Required
system_metadata.is_private	boolean	Privacy flag	Required
system_metadata.mime_type	string	MIME type of object	Required for files
system_metadata.file_extension	string	File extension	Required for files
system_metadata.file_size	number	Size in bytes	Required for files
system_metadata.is_latest_version	boolean	Latest version flag	Required
custom_metadata	object	Custom metadata	Optional
custom_metadata.kvp	object	Key-value pairs	Optional
custom_metadata.tags	array	Tags list	Optional
custom_metadata.taxonomy	array	Taxonomy information	Optional

{
  "object_id": "optional-uuid-if-client-wants-to-specify",
  "title": "Object Title",
  "description": "Object Description", 
  "system_metadata": {
    "source": "KnowledgeBase",
    "source_category": "Guideline",
    "is_private": false,
    "mime_type": "application/pdf",
    "file_extension": "pdf",
    "file_size": 1024,
    "is_latest_version": true
  },
  "custom_metadata": {
    "kvp": {
      "key1": "value1"
    },
    "tags": [
      "tag1"
    ],
    "taxonomy": [
      {
        "uuid": "taxonomy-id",
        "title": "Taxonomy Title"
      }
    ]
  }
}

Response

{
  "status": "200",
  "message": "Object created successfully",
  "data": {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "version_id": "v1"
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "title": "Object Title",
    "description": "Object Description",
    "system_metadata": {
        "source": "KnowledgeBase",
        "source_category": "Guideline",
        "is_private": False,
        "mime_type": "application/pdf",
        "file_extension": "pdf",
        "file_size": 1024,
        "is_latest_version": True
    },
    "custom_metadata": {
        "kvp": {"key1": "value1"},
        "tags": ["tag1"],
        "taxonomy": [{"uuid": "taxonomy-id", "title": "Taxonomy Title"}]
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Object Update Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/objects/{object_id}
Summary: Updates an existing object's latest version.

Description

Updates an object in the repository. Can update metadata and content.

Request

Query Parameters
- object_id (path): UUID of the object to update
Payload

Field	Type	Description	Validation
title	string	Updated title	Optional
description	string	Updated description	Optional
system_metadata	object	Updated system metadata	Optional
system_metadata.is_private	boolean	Updated privacy flag	Optional
system_metadata.mime_type	string	Updated MIME type	Optional
system_metadata.file_extension	string	Updated file extension	Optional
system_metadata.file_size	number	Updated size in bytes	Optional
custom_metadata	object	Updated custom metadata	Optional
custom_metadata.kvp	object	Updated key-value pairs	Optional
custom_metadata.tags	array	Updated tags list	Optional
custom_metadata.taxonomy	array	Updated taxonomy info	Optional

{
  "title": "Updated Title",
  "description": "Updated Description",
  "system_metadata": {
    "is_private": true,
    "mime_type": "application/pdf",
    "file_extension": "pdf",
    "file_size": 2048
  },
  "custom_metadata": {
    "kvp": {
      "key1": "updated_value"
    },
    "tags": [
      "new_tag"
    ],
    "taxonomy": [
      {
        "uuid": "new-taxonomy-id",
        "title": "New Taxonomy"
      }
    ]
  }
}

Response

{
  "status": "200",
  "message": "Object updated successfully",
  "data": {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "version_id": "v2"
  }
}

Usage

import requests

object_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v2/objects/{object_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "title": "Updated Title",
    "description": "Updated Description",
    "system_metadata": {
        "is_private": True,
        "mime_type": "application/pdf",
        "file_extension": "pdf",
        "file_size": 2048
    },
    "custom_metadata": {
        "kvp": {"key1": "updated_value"},
        "tags": ["new_tag"],
        "taxonomy": [{"uuid": "new-taxonomy-id", "title": "New Taxonomy"}]
    }
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

Object Retrieval Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v2/objects/{object_id}
Summary: Retrieves an object by ID.

Description

Gets object details including all metadata and versions.

Request

Query Parameters
- object_id (path): UUID of the object to retrieve

Response

{
  "status": "200",
  "message": "Object found",
  "data": {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "title": "Object Title",
    "description": "Object Description",
    "system_metadata": {
      "source": "KnowledgeBase",
      "source_category": "Guideline",
      "is_private": false,
      "mime_type": "application/pdf",
      "file_extension": "pdf",
      "file_size": 1024,
      "is_latest_version": true,
      "created_by": "user-id",
      "created_by_name": "User Name",
      "created_at": "2024-08-05T12:31:23.939Z",
      "updated_by": "user-id",
      "updated_by_name": "User Name",
      "updated_at": "2024-08-05T18:36:02.772Z"
    },
    "custom_metadata": {
      "kvp": {
        "key1": "value1"
      },
      "tags": [
        "tag1"
      ],
      "taxonomy": [
        {
          "uuid": "taxonomy-id",
          "title": "Taxonomy Title"
        }
      ]
    },
    "versions": [
      {
        "version_id": "v1",
        "created_at": "2024-08-05T12:31:23.939Z",
        "created_by": "user-id",
        "created_by_name": "User Name"
      }
    ]
  }
}

Usaage

import requests

object_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v1/objects/{object_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.get(url, headers=headers)
print(response.json())

Object Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v2/objects/{object_id}
Summary: Deletes an object from the repository.

Description

Deletes the specified object and all its versions.

Request

Query Parameters
- object_id (path): UUID of the object to delete

Response

{
  "status": "200",
  "message": "Object deleted successfully"
}

Usage

import requests

object_id = "1ea3d628-f555-41c7-8101-c56a65087bab"
url = f"https://api.kadal.ai/cl/api/v2/objects/{object_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.delete(url, headers=headers)
print(response.json())

Objects Listing Endpoint

Method: GET
Path: https://api.kadal.ai/cl/api/v2/objects
Summary: Lists all objects in the repository.

Description

Gets a paginated list of all objects.

Request

Query Parameters
- page (optional): Page number (default: 1)
- size (optional): Items per page (default: 20)
- sort_by (optional): Field to sort by (title/updated_at)
- order (optional): Sort order (asc/desc)

Response

{
  "status": "200", 
  "message": "Objects found",
  "data": {
    "total": 50,
    "page": 1,
    "size": 20,
    "results": [
      {
        "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
        "title": "Object Title",
        "description": "Object Description",
        "system_metadata": {
          "source": "KnowledgeBase",
          "source_category": "Guideline",
          "is_private": false,
          "mime_type": "application/pdf",
          "file_extension": "pdf",
          "file_size": 1024,
          "is_latest_version": true,
          "created_at": "2024-08-05T12:31:23.939Z",
          "updated_at": "2024-08-05T18:36:02.772Z"
        },
        "custom_metadata": {
          "kvp": {
            "key1": "value1"
          },
          "tags": ["tag1"],
          "taxonomy": [{
            "uuid": "taxonomy-id",
            "title": "Taxonomy Title"
          }]
        }
      }
    ]
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects"
headers = {
    "Authorization": "Bearer <your_token>"
}
params = {
    "page": 1,
    "size": 20,
    "sort_by": "title",
    "order": "asc"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Move bulk folders and objects Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/objects/move/bulk
Summary: Move bulk folders and objects to a folder

Description

Move bulk folders and objects to a folder

Request

Payload

Field	Type	Description	Validation
object_ids	array	List of object UUIDs	Each item UUID
folder_ids	array	List of folder UUIDs	Each item UUID
update_fields	object	Fields to update	Required
update_fields.parent_id	string	Parent folder/object ID	UUID format
update_fields.is_private	boolean	Privacy flag for the object/folder	Required (true/false)

{
"object_ids": [
  "string"
],
"folder_ids": [
  "string"
],
"update_fields": {
  "parent_id": "string",
  "is_private": true
}
}

Response

{
  "status": "string",
  "message": "string",
  "data": {
    "status": "string",
    "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version_no": 1,
    "version_label": "string",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "object_type": "string",
    "title": "string",
    "description": "string",
    "file_name": "string",
    "file_extension": "string",
    "size": 0,
    "mimetype": "string",
    "uri": "string",
    "asset_location": "string",
    "default_asset_thumbnail": "string",
    "created_at": "2025-12-22T06:57:55.139Z",
    "updated_at": "2025-12-22T06:57:55.139Z",
    "deleted_at": "2025-12-22T06:57:55.139Z",
    "created_by_name": "string",
    "created_by_user_id": "string",
    "created_by_user_type": "string",
    "updated_by_name": "string",
    "deleted_by_name": "string",
    "is_latest_version": false,
    "is_deleted": false,
    "is_private": false,
    "is_lga": "string",
    "source": "string",
    "tags": [
      "string"
    ],
    "kvp": {},
    "taxonomy": [
      {
        "uuid": "string",
        "title": "string"
      }
    ],
    "folders": [
      "string"
    ],
    "repos": [
      "string"
    ],
    "metadata": {},
    "media": {},
    "usage_count": 0,
    "license_expiration_date": "2025-12-22T06:57:55.139Z",
    "license_validity": true
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/move/bulk"
headers = {
    "Authorization": "Bearer <your_token>"
}

payload = {
  "object_ids": [
    "string"
  ],
  "folder_ids": [
    "string"
  ],
  "update_fields": {
    "parent_id": "string",
    "is_private": true
  }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Create a new object association for usage count and associated objects Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/objects/associations
Summary: Create a new object association for usage count and associated objects. Here origin means the assets embedded. Here destination means the document where the assets are being embedded. Here mode can be ADD or REMOVE only.

Description

Create a new object association for usage count and associated objects. Here origin means the assets embedded. Here destination means the document where the assets are being embedded. Here mode can be ADD or REMOVE only.

Request

Payload

Field	Type	Description	Validation
id	string	Unique identifier for the relationship	UUID format
type	string	Type of relationship (e.g., isEmbeddedOf)	Required
origin	object	Origin object details	Required
origin.object_id	string	ID of the origin object	UUID format
origin.version_id	string	Version identifier of the origin object	UUID format
origin.version_no	number	Version number of the origin object	Integer, Required
destination	object	Destination object details	Required
destination.object_id	string	ID of the destination object	UUID format
destination.version_id	string	Version identifier of the destination object	UUID format
source	string	Source reference or metadata	Optional
mode	string	Operation mode (e.g., ADD, REMOVE, UPDATE)	Enum: ADD/REMOVE/UPDATE

{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "isEmbeddedOf",
"origin": {
  "object_id": "",
  "version_id": "",
  "version_no": 1
},
"destination": {
  "object_id": "",
  "version_id": ""
},
"source": "",
"mode": "ADD"
}

Response

{
  "id": "",
  "type": "isEmbeddedOf",
  "sequence_number": 1,
  "origin_object_id": "string",
  "origin_version_id": "string",
  "origin_version_no": 1,
  "origin_title": "",
  "origin_object_type": "",
  "origin_file_name": "",
  "origin_asset_location": "",
  "origin_file_extension": "",
  "associated_at": "2025-12-22T07:01:04.343Z",
  "associated_by": "",
  "destination_object_id": "string",
  "destination_version_id": "string"
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/associations"
headers = {
    "Authorization": "Bearer <your_token>"
}

payload = {
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "isEmbeddedOf",
  "origin": {
    "object_id": "",
    "version_id": "",
    "version_no": 1
  },
  "destination": {
    "object_id": "",
    "version_id": ""
  },
  "source": "",
  "mode": "ADD"
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

Deassociate the objects in Bulk Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/objects/deassociations/bulk
Summary: Deassociate the objects in Bulk

Description

Deassociate the objects in Bulk

Request

Payload

Field	Type	Description	Validation
ids	array	List of object identifiers to update	Each item UUID, Optional
mode	string	Operation mode for the request	Enum: REMOVE

{
"ids": [],
"mode": "REMOVE"
}

Response

{
  "status": "string",
  "message": "string",
  "data": [
    {
      "ids": [],
      "mode": "REMOVE"
    }
  ]
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/deassociations/bulk"
headers = {
    "Authorization": "Bearer <your_token>"
}

payload = {
  "ids": [],
  "mode": "REMOVE"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Get All Asset lists embedded for an Object Id for a specific version Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/objects/associations/<object_id>/versions/<version_id>
Summary: Get All Asset lists embedded for an Object Id for a specific version.

Description

Get All Asset lists embedded for an Object Id for a specific version.

Request

Payload

Field	Type	Description	Validation
object_id	string	UUID for the object	UUID format
version_id	string	UUID for the object	UUID format

Response

{
  "status": "string",
  "message": "string",
  "data": [
    {
      "id": "",
      "type": "isEmbeddedOf",
      "sequence_number": 1,
      "origin_object_id": "string",
      "origin_version_id": "string",
      "origin_version_no": 1,
      "origin_title": "",
      "origin_object_type": "",
      "origin_file_name": "",
      "origin_asset_location": "",
      "origin_file_extension": "",
      "associated_at": "2025-12-22T07:05:38.960Z",
      "associated_by": "",
      "destination_object_id": "string",
      "destination_version_id": "string"
    }
  ]
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/associations/<object_id>/versions/<version_id>"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.get(url, headers=headers, json=payload)
print(response.json())

Update the file for object in the object repository Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/objects/upload-file-from-generated-asset
Summary: Update the file for object in the object repository.

Description

Update the file for object in the object repository

Request

Payload

Field	Type	Description	Validation
title	string	Title of the asset or chat	Required
asset_id	string	Unique identifier for the asset	UUID format
chat_id	string	Unique identifier for the chat	UUID format
is_agent_chat	boolean	Flag indicating if the chat is agent-based	Required (true/false)
parent_folder_id	string	Identifier of the parent folder	UUID format, Optional
is_private	boolean	Privacy flag for the asset/chat	Required (true/false)

{
"title": "string",
"asset_id": "string",
"chat_id": "string",
"is_agent_chat": true,
"parent_folder_id": "string",
"is_private": false
}

Response

{
  "status": "string",
  "message": "string",
  "data": {
    "status": "string",
    "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "version_no": 1,
    "version_label": "string",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "object_type": "string",
    "title": "string",
    "description": "string",
    "file_name": "string",
    "file_extension": "string",
    "size": 0,
    "mimetype": "string",
    "uri": "string",
    "asset_location": "string",
    "default_asset_thumbnail": "string",
    "created_at": "2025-12-22T09:09:21.962Z",
    "updated_at": "2025-12-22T09:09:21.962Z",
    "deleted_at": "2025-12-22T09:09:21.962Z",
    "created_by_name": "string",
    "created_by_user_id": "string",
    "created_by_user_type": "string",
    "updated_by_name": "string",
    "deleted_by_name": "string",
    "is_latest_version": false,
    "is_deleted": false,
    "is_private": false,
    "is_lga": "string",
    "source": "string",
    "tags": [
      "string"
    ],
    "kvp": {},
    "taxonomy": [
      {
        "uuid": "string",
        "title": "string"
      }
    ],
    "folders": [
      "string"
    ],
    "repos": [
      "string"
    ],
    "metadata": {},
    "media": {},
    "usage_count": 0,
    "license_expiration_date": "2025-12-22T09:09:21.962Z",
    "license_validity": true
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/objects/upload-file-from-generated-asset"
headers = {
    "Authorization": "Bearer <your_token>"
}

payload = {
  "title": "string",
  "asset_id": "string",
  "chat_id": "string",
  "is_agent_chat": true,
  "parent_folder_id": "string",
  "is_private": false
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Chunks V2 APIs

Chunk Search Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/chunks/search
Summary: Search for chunks based on similarity search.

Description

Performs a semantic similarity search across chunks.

Request

Payload

{
  "query": "search text",
  "filters": {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "chunk_type": "text",
    "metadata": {
      "key": "value"
    }
  },
  "top_k": 10
}

Response

{
  "status_code": "200",
  "message": "Chunks found",
  "data": {
    "chunks": [{
      "chunk_id": "chunk123",
      "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
      "content": "chunk content",
      "metadata": {
        "key": "value"
      },
      "chunk_type": "text",
      "similarity_score": 0.95
    }]
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/chunks/search"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "query": "search text",
    "filters": {
        "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
        "chunk_type": "text"
    },
    "top_k": 10
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Chunk Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/chunks
Summary: Creates a new chunk in the repository.

Description

Creates a new chunk with content and metadata.

Request

Payload

Field	Type	Description	Validation
object_id	string	UUID of the associated object	Required, UUID format
content	string	Chunk content	Required
metadata	object	Metadata for the chunk	Optional
metadata.key	string	Metadata key	Optional
metadata.value	string	Metadata value	Optional
chunk_type	string	Type of the chunk	Required, Enum: text, file
embedding	object	Embedding information	Required for vector chunks
embedding.vector	array	Vector array (float)	Required for vector chunks
embedding.model	string	Model used for embedding	Required for vector chunks

{
  "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
  "content": "chunk content",
  "metadata": {
    "key": "value"
  },
  "chunk_type": "text",
  "embedding": {
    "vector": [0.1, 0.2, 0.3],
    "model": "gte-small"
  }
}

Response

{
  "status_code": "201",
  "message": "Chunk created",
  "data": {
    "chunk_id": "chunk123"
  }
}

Usage

import requests
import numpy as np

url = "https://api.kadal.ai/cl/api/v2/chunks"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "content": "chunk content",
    "metadata": {"key": "value"},
    "chunk_type": "text",
    "embedding": {
        "vector": np.random.rand(384).tolist(),  # Example vector
        "model": "gte-small"
    }
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Chunk Update Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/api/v2/chunks/{chunk_id}
Summary: Updates an existing chunk.

Description

Updates content or metadata of an existing chunk.

Request

Query Parameters
- chunk_id (path): ID of the chunk to update

Payload

{
  "content": "updated content",
  "metadata": {
    "key": "new_value"
  }
}

Response

{
  "status_code": "200",
  "message": "Chunk updated"
}

Usage

import requests

chunk_id = "chunk123"
url = f"https://api.kadal.ai/cl/api/v2/chunks/{chunk_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "content": "updated content",
    "metadata": {"key": "new_value"}
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

Chunk Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v2/chunks/{chunk_id}
Summary: Deletes a chunk.

Description

Removes a chunk from the repository.

Request

Query Parameters
- chunk_id (path): ID of the chunk to delete

Response

{
  "status_code": "200",
  "message": "Chunk deleted"
}

Usage

import requests

chunk_id = "chunk123"
url = f"https://api.kadal.ai/cl/api/v2/chunks/{chunk_id}"
headers = {
    "Authorization": "Bearer <your_token>"
}

response = requests.delete(url, headers=headers)
print(response.json())

Bulk Chunks Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/api/v2/chunks/bulk
Summary: Creates multiple chunks in a single request.

Description

Bulk creation of chunks.

Request

Payload

{
  "chunks": [{
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "content": "chunk content 1",
    "metadata": {
      "key": "value1"
    }
  },
  {
    "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "content": "chunk content 2",
    "metadata": {
      "key": "value2"
    }
  }]
}

Response

{
  "status_code": "201",
  "message": "Chunks created",
  "data": {
    "chunk_ids": ["chunk123", "chunk124"]
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/chunks/bulk"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "chunks": [{
        "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
        "content": "chunk content 1",
        "metadata": {"key": "value1"}
    },
    {
        "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
        "content": "chunk content 2",
        "metadata": {"key": "value2"}
    }]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Bulk Chunks Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/api/v2/chunks/object/bulk
Summary: Deletes all chunks for an object.

Description

Removes all chunks associated with specified objects.

Request

Payload

{
  "object_ids": [
    "1ea3d628-f555-41c7-8101-c56a65087bab",
    "2fb4d839-g666-52d8-9212-d67b76198bac"
  ]
}

Response

{
  "status_code": "200",
  "message": "Object chunks deleted"
}

Usage

import requests

url = "https://api.kadal.ai/cl/api/v2/chunks/object/bulk"
headers = {
    "Authorization": "Bearer <your_token>"
}
payload = {
    "object_ids": [
        "1ea3d628-f555-41c7-8101-c56a65087bab",
        "2fb4d839-g666-52d8-9212-d67b76198bac"
    ]
}

response = requests.delete(url, headers=headers, json=payload)
print(response.json())

File Upload V3 APIs

Upload Files

Method: POST
Path: https://api.kadal.ai/cl/api/v3/file_upload
Summary: Upload files to the chat interface.

Description

Uploads files to the chat interface with support for various file types.

Request

Query Parameters
- files (form-data, required): List of files to upload
- folder_id (query, required): The my folder ID where files should be uploaded
- source_category (query, required): Category of the source (KnowledgeBase/Guideline/OutputTemplate/InputFile)
- session_id (query, required): Chat interface session ID

Response

{
  "status_code": "200",
  "message": "Files uploaded successfully",
  "data": {
    "files": [{
      "file_name": "document.pdf",
      "object_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
      "status": "uploaded"
    }]
  }
}

Other Responses
- 413 Payload Too Large: File size exceeds limit
- 415 Unsupported Media Type: Invalid file type

Usage

import requests

url = "https://api.kadal.ai/cl/api/v3/file_upload"
headers = {
    "Authorization": "Bearer <your_token>"
}
params = {
    "folder_id": "1ea3d628-f555-41c7-8101-c56a65087bab",
    "source_category": "KnowledgeBase",
    "session_id": "5678"
}
files = {
    'files': [
        ('document.pdf', open('document.pdf', 'rb'), 'application/pdf'),
        ('image.jpg', open('image.jpg', 'rb'), 'image/jpeg')
    ]
}

response = requests.post(url, headers=headers, params=params, files=files)
print(response.json())

Directory APIs​

Root Directory Retrieval Endpoint​

Description​

Request​

Query Parameters​

Response​

Usage​

Root Directory Creation Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Other Responses​

Usage​

Directory Retrieval Endpoint​

Description​

Request​

Query Parameters​

Response​

Directory Metadata Update Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Usage​

Child Directories Addition Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Other Responses​

Usage​

Directory Deletion Endpoint​

Description​

Request​

Query Parameters​

Response​

Usage​

Bulk Directory Retrieval Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Directory Search Endpoint​

Description​

Request​

Query Parameters​

Response​

My Folder APIs​

My Folder Upsert Endpoint​

Description​

Response​

Other Responses​

Notes​

Usage​

Objects V2 APIs​

Object Creation Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Object Update Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Usage​

Object Retrieval Endpoint​

Description​

Request​

Query Parameters​

Response​

Usaage​

Object Deletion Endpoint​

Directory APIs

Root Directory Retrieval Endpoint

Description

Request

Query Parameters

Response

Usage

Root Directory Creation Endpoint

Description

Request

Query Parameters

Payload

Response

Other Responses

Usage

Directory Retrieval Endpoint

Description

Request

Query Parameters

Response

Directory Metadata Update Endpoint

Description

Request

Query Parameters

Payload

Response

Usage

Child Directories Addition Endpoint

Description

Request

Query Parameters

Payload

Response

Other Responses

Usage

Directory Deletion Endpoint

Description

Request

Query Parameters

Response

Usage

Bulk Directory Retrieval Endpoint

Description

Request

Query Parameters

Payload

Response

Directory Search Endpoint

Description

Request

Query Parameters

Response

My Folder APIs

My Folder Upsert Endpoint

Description

Response

Other Responses

Notes

Usage

Objects V2 APIs

Object Creation Endpoint

Description

Request

Payload

Response

Usage

Object Update Endpoint

Description

Request

Query Parameters

Payload

Response

Usage

Object Retrieval Endpoint

Description

Request

Query Parameters

Response

Usaage

Object Deletion Endpoint