Version: 1.3.0

Search API Documentation

Re-ranked Chunk Search Endpoint

Method: POST
Path: https://api.kadal.ai/cl/search/api/v2/chunk/search
Summary: Search the database for similar chunks using k-nn and full text search

Description

Search the database for similar chunks present using k-nn search and full text search provided by mongoDb Vector. If you would like to search for a specific set of chunks, you can provide the object_ids in the request as list of strings.

Request

Content-Type: application/json
Authentication: Bearer Token Required

Payload

Parameter	Description	Data Type	Required
query_string	Search query string	String	Yes (Query)
page_size	Number of results per page	Integer	No (Query, Default: 5)
page_no	Page number	Integer	No (Query, Default: 1)
object_ids	List of specific object IDs to search in	Array	No
custom_metadata	Custom metadata filters	Object	No

Response

{
  "status": "200",
  "message": "Chunks found successfully",
  "data": []
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/search/api/v2/chunk/search"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "query_string": "machine learning",
    "page_size": 10,
    "page_no": 1
}

data = {
    "object_ids": ["obj1", "obj2"],
    "custom_metadata": {
        "tags": [],
        "kvp": [],
        "taxonomy": []
    }
}

# Make the POST request
response = requests.post(url, headers=headers, params=params, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Re-ranked Search Endpoint

Method: POST
Path: https://api.kadal.ai/cl/search/api/v2/search
Summary: Re-rank the search results obtained through semantic and fulltext search

Description

Re-rank the search results obtained through semantic and fulltext search to improve relevance and accuracy of search results.

Request

Content-Type: application/json
Authentication: Bearer Token Required

Payload

Parameter	Description	Data Type	Allowed Values	Required
query_string	Search query string	String		Yes (Query)
re_ranked	Enable re-ranking	Boolean	true, false	No (Query, Default: true)
page_no	Page number	Integer		No (Query, Default: 1)
page_size	Number of results per page	Integer		No (Query, Default: 20)
object_ids	List of specific object IDs to search in	Array		No
folders	List of folders to search in	Array		No
object_type	List of object types to filter	Array	Document, Audio, Video, Image, Course, etc.	No
file_extension	File extensions to filter	Array	pdf, docx, pptx, mp4, mp3, jpg, png, etc.	No

Response

{
  "status": "200",
  "message": "Search results retrieved successfully",
  "data": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/search/api/v2/search"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "query_string": "artificial intelligence",
    "re_ranked": True,
    "page_no": 1,
    "page_size": 20
}

data = {
    "object_ids": ["obj1", "obj2"],
    "folders": ["folder1", "folder2"],
    "object_type": ["Document", "Video"],
    "file_extension": ["pdf", "mp4"],
    "title": "",
    "size": 0,
    "ext_user_id_ref": "",
    "custom_metadata": {
        "tags": [],
        "kvp": [],
        "taxonomy": []
    },
    "media_metadata": {},
    "source_system_metadata": {
        "source_system_id": "",
        "connector_info": {},
        "source_url": ""
    }
}

# Make the POST request
response = requests.post(url, headers=headers, params=params, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Basic Search Endpoint (V2)

Method: POST
Path: https://api.kadal.ai/cl/search/api/v2/basic_search
Summary: Basic search on tenant data present

Description

Return a list of all the objects that are present in the object repository for a query under that particular tenant's ID.

Request

Content-Type: application/json
Authentication: Bearer Token Required

Payload

Parameter	Description	Data Type	Allowed Values	Required
query_string	Query string to search for objects	String		No (Query)
sorting_by	Field to sort by	String	None, title, updated_at	No (Query, Default: None)
order	Sort order	String	None, asc, desc	No (Query, Default: asc)
page_no	Page number	Integer		No (Query, Default: 1)
page_size	Number of results per page	Integer		No (Query, Default: 20)
object_ids	List of specific object IDs	Array		No
folders	List of folders to search in	Array		No
object_type	List of object types	Array	Document, Audio, Video, Image, etc.	No
file_extension	File extensions to filter	Array	pdf, docx, pptx, mp4, etc.	No
with_exact_search	Enable exact search	Boolean	true, false	No (Default: false)
with_highlight	Enable highlighting	Boolean	true, false	No (Default: false)
is_anywhere	Search anywhere flag	Boolean	true, false	No (Default: false)

Response

{
  "status": "200",
  "message": "Documents found",
  "result_count": 0,
  "result": [],
  "aggregation": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/search/api/v2/basic_search"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "query_string": "machine learning",
    "sorting_by": "title",
    "order": "asc",
    "page_no": 1,
    "page_size": 20
}

data = {
    "object_ids": [],
    "folders": [],
    "object_type": ["Document"],
    "file_extension": ["pdf", "docx"],
    "title": "",
    "size": 0,
    "file_name": [],
    "repos": [],
    "ext_user_id_ref": "",
    "system_metadata": {
        "created_by": "",
        "updated_by": "",
        "is_deleted": False,
        "is_lga": "",
        "source": "",
        "created_by_name": "",
        "updated_by_name": "",
        "deleted_by_name": ""
    },
    "custom_metadata": {
        "tags": [],
        "kvp": [],
        "taxonomy": []
    },
    "media_metadata": {},
    "source_system_metadata": {
        "source_system_id": "",
        "connector_info": {},
        "source_url": ""
    },
    "with_exact_search": False,
    "with_highlight": False,
    "is_anywhere": False
}

# Make the POST request
response = requests.post(url, headers=headers, params=params, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Full-Text Search Endpoint

Method: POST
Path: https://api.kadal.ai/cl/search/api/v2/fulltext
Summary: Full-Text search on tenant data present

Description

Return a list of all the objects that are present in the object repository for the full-text search request.

Request

Content-Type: application/json
Authentication: Bearer Token Required

Payload

Parameter	Description	Data Type	Allowed Values	Required
query_string	Query string to search for objects	String		Yes (Query)
sorting_by	Field to sort by	String	None, title, updated_at	No (Query, Default: None)
order	Sort order	String	None, asc, desc	No (Query, Default: asc)
page_no	Page number	Integer		No (Query, Default: 1)
page_size	Number of results per page	Integer		No (Query, Default: 20)
min_relevant_score	Minimum relevance score	Number		No (Query, Default: 0.5)
object_ids	List of specific object IDs	Array		No
folders	List of folders to search in	Array		No
object_type	List of object types	Array	Document, Audio, Video, Image, etc.	No
file_extension	File extensions to filter	Array	pdf, docx, pptx, mp4, etc.	No
is_anywhere	Search anywhere flag	Boolean	true, false	No (Default: false)

Response

{
  "status": "200",
  "message": "Documents found",
  "result_count": 0,
  "result": [],
  "aggregation": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/search/api/v2/fulltext"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "query_string": "artificial intelligence",
    "sorting_by": "title",
    "order": "asc",
    "page_no": 1,
    "page_size": 20,
    "min_relevant_score": 0.5
}

data = {
    "object_ids": [],
    "folders": [],
    "object_type": ["Document"],
    "file_extension": ["pdf", "docx"],
    "title": "",
    "size": 0,
    "file_name": [],
    "repos": [],
    "ext_user_id_ref": "",
    "system_metadata": {
        "created_by": "",
        "updated_by": "",
        "is_deleted": False,
        "is_lga": "",
        "source": "",
        "created_by_name": "",
        "updated_by_name": "",
        "deleted_by_name": ""
    },
    "custom_metadata": {
        "tags": [],
        "kvp": [],
        "taxonomy": []
    },
    "media_metadata": {},
    "source_system_metadata": {
        "source_system_id": "",
        "connector_info": {},
        "source_url": ""
    },
    "is_anywhere": False
}

# Make the POST request
response = requests.post(url, headers=headers, params=params, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Semantic Search Endpoint

Method: POST
Path: https://api.kadal.ai/cl/search/api/v2/semantic
Summary: Semantic search on tenant data present

Description

Return a list of all the objects that are present in the object repository for the Semantic search request.

Request

Content-Type: application/json
Authentication: Bearer Token Required

Payload

Parameter	Description	Data Type	Allowed Values	Required
query_string	Query string to search for objects	String		Yes (Query)
sorting_by	Field to sort by	String	None, title, updated_at	No (Query, Default: None)
order	Sort order	String	None, asc, desc	No (Query, Default: asc)
page_no	Page number	Integer		No (Query, Default: 1)
page_size	Number of results per page	Integer		No (Query, Default: 20)
min_relevant_score	Minimum relevance score	Number		No (Query, Default: 0.5)
object_ids	List of specific object IDs	Array		No
folders	List of folders to search in	Array		No
object_type	List of object types	Array	Document, Audio, Video, Image, etc.	No
file_extension	File extensions to filter	Array	pdf, docx, pptx, mp4, etc.	No
is_anywhere	Search anywhere flag	Boolean	true, false	No (Default: false)

Response

{
  "status": "200",
  "message": "Documents found",
  "result_count": 0,
  "result": [],
  "aggregation": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/search/api/v2/semantic"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "query_string": "machine learning algorithms",
    "sorting_by": "title",
    "order": "asc",
    "page_no": 1,
    "page_size": 20,
    "min_relevant_score": 0.5
}

data = {
    "object_ids": [],
    "folders": [],
    "object_type": ["Document"],
    "file_extension": ["pdf", "docx"],
    "title": "",
    "size": 0,
    "file_name": [],
    "repos": [],
    "ext_user_id_ref": "",
    "system_metadata": {
        "created_by": "",
        "updated_by": "",
        "is_deleted": False,
        "is_lga": "",
        "source": "",
        "created_by_name": "",
        "updated_by_name": "",
        "deleted_by_name": ""
    },
    "custom_metadata": {
        "tags": [],
        "kvp": [],
        "taxonomy": []
    },
    "media_metadata": {},
    "source_system_metadata": {
        "source_system_id": "",
        "connector_info": {},
        "source_url": ""
    },
    "is_anywhere": False
}

# Make the POST request
response = requests.post(url, headers=headers, params=params, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Classify and Re-rank Search Endpoint (V3)

Method: POST
Path: https://api.kadal.ai/cl/search/api/v3/classify_rerank_search
Summary: Classify the query and Re-rank the search results

Description

Classify the query and Re-rank the search results obtained through semantic and fulltext search.

Request

Content-Type: application/x-www-form-urlencoded
Authentication: Bearer Token Required
Payload
Parameter Description Data Type Allowed Values Required
query_string Search query string String Yes

Parameter	Description	Data Type	Allowed Values	Required
query_string	Search query string	String		Yes

Response

{
  "status": "200",
  "message": "Search results classified and ranked successfully",
  "data": {}
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/search/api/v3/classify_rerank_search"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/x-www-form-urlencoded"
}

data = {
    "query_string": "machine learning algorithms"
}

# Make the POST request
response = requests.post(url, headers=headers, data=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Basic Search Endpoint (V3)

Method: POST
Path: https://api.kadal.ai/cl/search/api/v3/basic_search
Summary: Basic search on tenant data present with folders and objects combined

Description

Return a list of all the folders and objects combined that are present in the object repository for a query under that particular tenant's ID.

Request

Content-Type: application/json
Authentication: Bearer Token Required

Payload

Parameter	Description	Data Type	Allowed Values	Required
query_string	Query string to search for folders and objects	String		No (Query)
sorting_by	Field to sort by	String	score, title, updated_at	No (Query, Default: score)
order	Sort order	String	asc, desc	No (Query, Default: desc)
page_no	Page number	Integer		No (Query, Default: 1)
page_size	Number of results per page	Integer		No (Query, Default: 50)
search_keys	Fields to search in	Array	title, description, file_name, etc.	No
object_ids	List of specific object IDs	Array		No
folders	List of folders to search in	Array		No
object_type	List of object types	Array	Document, Audio, Video, Image, etc.	No
file_extension	File extensions to filter	Array	pdf, docx, pptx, mp4, etc.	No
with_exact_search	Enable exact search	Boolean	true, false	No (Default: false)
with_highlight	Enable highlighting	Boolean	true, false	No (Default: false)
is_anywhere	Search anywhere flag	Boolean	true, false	No (Default: false)
is_combinedobjects	Combine objects flag	Boolean	true, false	No (Default: true)
has_folderonly	Folder only flag	Boolean	true, false	No (Default: false)

Response

{
  "status": "200",
  "message": "Documents found",
  "result_count": 0,
  "folder_result_count": 0,
  "object_result_count": 0,
  "result": []
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/search/api/v3/basic_search"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "query_string": "machine learning",
    "sorting_by": "score",
    "order": "desc",
    "page_no": 1,
    "page_size": 50
}

data = {
    "search_keys": [
        "title",
        "description",
        "file_name",
        "custom_metadata.tags.name",
        "custom_metadata.kvp.key",
        "custom_metadata.kvp.value",
        "custom_metadata.taxonomy.title",
        "custom_metadata.taxonomy.code",
        "media_metadata.image_details.metadata.alt_text",
        "media_metadata.image_details.metadata.captions",
        "media_metadata.image_details.metadata.ocr_text",
        "media_metadata.image_details.metadata.design_critique",
        "custom_metadata.category.name"
    ],
    "object_ids": [],
    "folders": [],
    "object_type": ["Document"],
    "file_extension": ["pdf", "docx"],
    "title": "",
    "size": 0,
    "file_name": [],
    "repos": [],
    "ext_user_id_ref": "",
    "system_metadata": {
        "created_by": "",
        "updated_by": "",
        "is_private": "",
        "is_deleted": False,
        "is_lga": "",
        "license_validity": "",
        "source": "",
        "created_by_name": "",
        "updated_by_name": "",
        "deleted_by_name": ""
    },
    "custom_metadata": {
        "tags": [],
        "kvp": [],
        "taxonomy": []
    },
    "media_metadata": {},
    "source_system_metadata": {
        "source_system_id": "",
        "connector_info": {},
        "source_url": ""
    },
    "with_exact_search": False,
    "with_highlight": False,
    "is_anywhere": False,
    "is_combinedobjects": True,
    "has_folderonly": False
}

# Make the POST request
response = requests.post(url, headers=headers, params=params, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Search API Documentation

Re-ranked Chunk Search Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Re-ranked Search Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Basic Search Endpoint (V2)​

Description​

Request​

Payload​

Response​

Usage​

Full-Text Search Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Semantic Search Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Classify and Re-rank Search Endpoint (V3)​

Description​

Request​

Payload​

Response​

Usage​

Basic Search Endpoint (V3)​

Description​

Request​

Payload​

Response​

Usage​

Re-ranked Chunk Search Endpoint

Description

Request

Payload

Response

Usage

Re-ranked Search Endpoint

Description

Request

Payload

Response

Usage

Basic Search Endpoint (V2)

Description

Request

Payload

Response

Usage

Full-Text Search Endpoint

Description

Request

Payload

Response

Usage

Semantic Search Endpoint

Description

Request

Payload

Response

Usage

Classify and Re-rank Search Endpoint (V3)

Description

Request

Payload

Response

Usage

Basic Search Endpoint (V3)

Description

Request

Payload

Response

Usage