Knowledge Search

Overview

The Knowledge Search endpoint is an intelligent document search and question-answering system powered by AI that provides accurate answers from your knowledge base with source citations. It uses advanced natural language processing to understand questions and retrieve relevant information from your uploaded documents.

Use this endpoint to:

Ask natural language questions about your documents
Extract specific information with AI-powered search
Get answers with source citations and page references
Build intelligent chatbots and Q&A systems
Implement document-based knowledge retrieval in your applications

Endpoint Details

Method: POST
Endpoint: /api/agent/k_search
Base URL: https://api.k-v.ai
Authentication: Access Key (Required)

Request Specification

Headers

Header	Type	Required	Description
access-key	string	Yes	Your unique access-key generated from the platform UI
Content-Type	string	Yes	Must be application/json

Request Body

{
    "doc_process_ids": ["264dfa262b748d15ccbeaada89430c68"],
    "question": "What are the parties involved?",
    "context": "concise",
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
}

Body Fields

Field	Type	Required	Description
doc_process_ids	array	Yes	Array of document IDs to search within (obtained from Upload or List Documents APIs)
question	string	Yes	Natural language question to ask about your documents
context	string	No	Response detail level: concise, medium, or extended (default: medium)
model_data	object	Yes	AI model configuration
model_data.model_name	string	Yes	AI model to use for processing (see supported models below)
model_data.api_key	string	No	Your own LLM API key (leave empty to use platform's default keys)

Supported AI Models

Model Name	Provider
gpt-5.1	OpenAI
gpt-5-mini	OpenAI
claude-sonnet-4-5-20250929	Anthropic
gemini/gemini-2.5-flash-lite	Google
gemini/gemini-2.5-pro	Google
gemini/gemini-3-pro-preview	Google
mistral/mistral-small-latest	Mistral AI
mistral/mistral-medium-latest	Mistral AI
llama3.1-70b	Meta

Context Levels

Context	Description
concise	Brief, direct answer with key points only
medium	Balanced response with explanations
extended	Comprehensive detailed analysis

Using Your Own LLM API Keys

Platform Keys (Default)

{
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
}

Your Own Keys

{
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": "sk-your-openai-api-key-here"
    }
}

Response Specification

Success Response (200 OK)

{
    "data": {
        "answer": "The parties involved are:\n\n- **ABC Software Corporation** (referred to as the **Plaintiff**)  \n- **Widget Corporation** (referred to as the **Defendant**)",
        "sources": [
            {
                "content": "SETTLEMENT AGREEMENT AND RELEASE...",
                "score": 0.38453761232252937,
                "filename": "Settlement Agreement (1).pdf",
                "doc_hash": "264dfa262b748d15ccbeaada89430c68",
                "page_number": 1
            }
        ]
    },
    "message": "Question processed successfully"
}

Response Fields

Field	Type	Description
data	object	Response data object
data.answer	string	AI-generated answer to your question with citations
data.sources	array	Array of source excerpts used to generate the answer
data.sources[].content	string	Relevant text excerpt from the document
data.sources[].score	float	Relevance score
data.sources[].filename	string	Original filename of the source document
data.sources[].doc_hash	string	Document process ID (same as doc_process_id)
data.sources[].page_number	integer	Page number where the content was found
message	string	Human-readable response message

Error Responses

401 Unauthorized

{
    "data": {},
    "message": "Invalid or missing access key"
}

Cause: Missing or invalid access-key header.

422 Unprocessable Entity - Invalid Context

{
    "detail": [
        {
            "type": "literal_error",
            "loc": [
                "body",
                "context"
            ],
            "msg": "Input should be 'concise', 'medium' or 'extended'",
            "input": "",
            "ctx": {
                "expected": "'concise', 'medium' or 'extended'"
            }
        }
    ]
}

Cause: Invalid value for context parameter. Must be one of: concise, medium, or extended.

422 Unprocessable Entity - Invalid Model Name

{
    "detail": [
        {
            "type": "literal_error",
            "loc": [
                "body",
                "model_data",
                "model_name"
            ],
            "msg": "Input should be 'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'",
            "input": "",
            "ctx": {
                "expected": "'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'"
            }
        }
    ]
}

Cause: Invalid or unsupported model_name in model_data. See supported models list above.

400 Bad Request - Missing Question

{
    "data": {},
    "message": "query not provided"
}

Cause: The question field is empty or missing from the request body.

400 Bad Request - Invalid Document IDs

{
    "data": {},
    "message": "Invalid docs selected"
}

Causes:

Missing or invalid doc_process_ids.

500 Internal Server Error - Invalid LLM API Key

{
    "data": {},
    "message": "litellm.AuthenticationError: AuthenticationError: OpenAIException - Incorrect API key provided: tyrdfuih**uhf7. You can find your API key at https://platform.openai.com/account/api-keys."
}

Cause: The api_key provided in model_data is invalid or expired. Verify your LLM provider API key.

500 Internal Server Error - General Error

{
    "data": {},
    "message": "Something went wrong"
}

Causes:

LLM service temporarily unavailable
Server-side processing error

Code Snippets

curl --location 'https://api.k-v.ai/api/agent/k_search' \
--header 'access-key: YOUR_ACCESS_KEY' \
--header 'Content-Type: application/json' \
--data '{
   "doc_process_ids": ["264dfa262b748d15ccbeaada89430c68"],
   "question": "what are the parties involved?",
   "context": "concise",
   "model_data": {
       "model_name": "gpt-5.1",
       "api_key": ""
   }
}'

import requests
import json

url = "https://api.k-v.ai/api/agent/k_search"

payload = json.dumps({
  "doc_process_ids": [
    "264dfa262b748d15ccbeaada89430c68"
  ],
  "question": "what are the parties involved?",
  "context": "concise",
  "model_data": {
    "model_name": "gpt-5.1",
    "api_key": ""
  }
})
headers = {
  'access-key': 'YOUR_ACCESS_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

const axios = require('axios');
let data = JSON.stringify({
  "doc_process_ids": [
    "264dfa262b748d15ccbeaada89430c68"
  ],
  "question": "what are the parties involved?",
  "context": "concise",
  "model_data": {
    "model_name": "gpt-5.1",
    "api_key": ""
  }
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.k-v.ai/api/agent/k_search',
  headers: { 
    'access-key': 'YOUR_ACCESS_KEY', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Important Notes

Document Processing: Only search documents with status: "processed" from List Documents API
Question Quality: More specific questions yield better answers

Next Steps

After using Knowledge Search:

Refine Questions: Iterate on question phrasing for better results
Analyze Sources: Review source scores and citations for accuracy
Build Applications: Integrate into chatbots, Q&A systems, or workflows

Need Help? Contact support at support@k-v.ai

Knowledge Search

On this page