Skip to main content
POST
/
v1
/
knowledge
/
chat
Chat with Knowledge Base
curl --request POST \
  --url https://api.bland.ai/v1/knowledge/chat \
  --header 'authorization: <authorization>' \
  --header 'content-type: <content-type>' \
  --data '
{
  "messages": [
    {
      "messages[].role": "<string>",
      "messages[].content": "<string>"
    }
  ],
  "knowledge_base_id": "<string>"
}
'
import requests

url = "https://api.bland.ai/v1/knowledge/chat"

payload = {
    "messages": [
        {
            "messages[].role": "<string>",
            "messages[].content": "<string>"
        }
    ],
    "knowledge_base_id": "<string>"
}
headers = {
    "authorization": "<authorization>",
    "content-type": "<content-type>"
}

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

print(response.text)
const options = {
  method: 'POST',
  headers: {authorization: '<authorization>', 'content-type': '<content-type>'},
  body: JSON.stringify({
    messages: [{'messages[].role': '<string>', 'messages[].content': '<string>'}],
    knowledge_base_id: '<string>'
  })
};

fetch('https://api.bland.ai/v1/knowledge/chat', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v1/knowledge/chat",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'messages' => [
        [
                'messages[].role' => '<string>',
                'messages[].content' => '<string>'
        ]
    ],
    'knowledge_base_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "authorization: <authorization>",
    "content-type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v1/knowledge/chat"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"messages[].role\": \"<string>\",\n      \"messages[].content\": \"<string>\"\n    }\n  ],\n  \"knowledge_base_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("authorization", "<authorization>")
	req.Header.Add("content-type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.bland.ai/v1/knowledge/chat")
  .header("authorization", "<authorization>")
  .header("content-type", "<content-type>")
  .body("{\n  \"messages\": [\n    {\n      \"messages[].role\": \"<string>\",\n      \"messages[].content\": \"<string>\"\n    }\n  ],\n  \"knowledge_base_id\": \"<string>\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/knowledge/chat")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["content-type"] = '<content-type>'
request.body = "{\n  \"messages\": [\n    {\n      \"messages[].role\": \"<string>\",\n      \"messages[].content\": \"<string>\"\n    }\n  ],\n  \"knowledge_base_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "response": "Our refund policy allows for full refunds within 30 days of purchase. For products purchased more than 30 days ago, we offer store credit or exchanges. Please contact our customer service team at support@example.com to initiate a refund request.",
    "context": "Based on company policy documentation regarding refunds and returns",
    "sources": [
      {
        "id": "doc_01H8X9QK5R2N7P3M6Z8W4Y1V7V",
        "content": "Refund Policy: Full refunds are available within 30 days of purchase...",
        "metadata": {
          "document_type": "policy",
          "section": "refunds",
          "last_updated": "2025-01-01"
        }
      }
    ]
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "KB_ERROR",
      "message": "Knowledge base not found or not accessible"
    }
  ]
}
Query a knowledge base using natural language and receive contextual responses. This endpoint supports both direct queries and conversational context through message history.

​
Headers

​
authorization
string
required
Your API key for authentication.
​
content-type
string
required
Must be application/json.

​
Body Parameters

​
messages
array
Array of chat messages for conversational context. Use this for multi-turn conversations.
​
messages[].role
string
required
The role of the message sender (e.g., “user”, “assistant”, “system”).
​
messages[].content
string
required
The content of the message.
​
knowledge_base_id
string
required
The ID of the knowledge base to query against.

​
Response

​
data
object
Chat response with contextual information.
​
data.response
string
The AI-generated response based on the knowledge base content.
​
data.context
string
Additional context information used to generate the response.
​
data.sources
array
Array of source documents that were used to generate the response.
​
data.sources[].id
string
Unique identifier of the source document.
​
data.sources[].content
string
Relevant content from the source document.
​
data.sources[].metadata
object
Additional metadata about the source document.
​
errors
null
Will be null on successful query.
{
  "data": {
    "response": "Our refund policy allows for full refunds within 30 days of purchase. For products purchased more than 30 days ago, we offer store credit or exchanges. Please contact our customer service team at support@example.com to initiate a refund request.",
    "context": "Based on company policy documentation regarding refunds and returns",
    "sources": [
      {
        "id": "doc_01H8X9QK5R2N7P3M6Z8W4Y1V7V",
        "content": "Refund Policy: Full refunds are available within 30 days of purchase...",
        "metadata": {
          "document_type": "policy",
          "section": "refunds",
          "last_updated": "2025-01-01"
        }
      }
    ]
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "KB_ERROR",
      "message": "Knowledge base not found or not accessible"
    }
  ]
}
Docs for agents: llms.txt