Chat API

Overview

The Chat API provides access to Khoj’s conversational AI capabilities. It supports multi-turn conversations, context-aware responses, document references, online search, code execution, and more.

Key Features

Context-Aware: Maintains conversation history and references previous messages
Multi-Modal: Supports text, images, and file attachments
Tool Integration: Can search documents, browse web, run code, and operate browser
Streaming: Real-time response streaming for better UX
Agent Support: Use custom agents with specialized capabilities

Start a Chat

Send a message and get a response from Khoj.

cURL

curl -X POST https://app.khoj.dev/api/chat \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "What are the main points from my meeting notes?",
    "stream": false
  }'

Python

import requests

headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
data = {
    "q": "What are the main points from my meeting notes?",
    "stream": False
}

response = requests.post(
    "https://app.khoj.dev/api/chat",
    headers=headers,
    json=data
)
result = response.json()

Request Body

string

required

The user’s message or query

conversation_id

string

ID of existing conversation to continue. If not provided, creates a new conversation.

stream

boolean

default:"true"

Whether to stream the response in real-time

integer

default:"5"

Number of document references to retrieve for context

images

array

Array of base64-encoded images to include with the message

files

array

Array of file objects with name and content fields

create_new

boolean

default:"false"

Force creation of a new conversation

title

string

Title for a new conversation

city

string

User’s city for location-aware responses

region

string

User’s region/state

country

string

User’s country

timezone

string

User’s timezone (e.g., “America/New_York”)

Response

status

string

Status of the request (“ok” or “error”)

response

string

The AI’s response message

conversationId

string

ID of the conversation for follow-up messages

turnId

string

Unique ID for this message turn

Example Response

{
  "response": "Based on your meeting notes, the main points were:\n1. Q4 roadmap priorities\n2. New feature launches\n3. Team expansion plans",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "turnId": "660e8400-e29b-41d4-a716-446655440001"
}

Streaming Responses

For real-time streaming, set stream: true. The response will be sent as Server-Sent Events (SSE).

Python Streaming

import requests
import json

headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
data = {"q": "Explain quantum computing", "stream": True}

response = requests.post(
    "https://app.khoj.dev/api/chat",
    headers=headers,
    json=data,
    stream=True
)

for line in response.iter_lines():
    if line:
        event_data = json.loads(line.decode('utf-8'))
        if event_data.get('type') == 'message':
            print(event_data['data'], end='', flush=True)

Stream Event Types

type: metadata

object

Contains conversation ID and turn ID at the start of the stream

type: status

string

Status updates during processing (e.g., “Searching documents…”, “Reading web pages…”)

type: thought

string

AI’s reasoning process (chain of thought)

type: references

object

Document references and context used

type: message

string

Actual response text (streamed token by token)

type: usage

object

Token usage and cost information

Conversation Management

Get Conversation History

Retrieve messages from a conversation.

curl "https://app.khoj.dev/api/chat/history?conversation_id=CONV_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

conversation_id

string

Conversation ID to retrieve. If not provided, gets the most recent conversation.

integer

Number of messages to retrieve. Positive values get the N most recent messages, negative values get all except the N most recent.

Response

{
  "status": "ok",
  "response": {
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "meeting-notes-discussion",
    "agent": {
      "slug": "khoj",
      "name": "Khoj",
      "color": "#7C3AED",
      "icon": "🦾"
    },
    "chat": [
      {
        "message": "What were the key points?",
        "by": "you",
        "created": "2024-03-05 10:30:00"
      },
      {
        "message": "The key points were...",
        "by": "khoj",
        "created": "2024-03-05 10:30:15"
      }
    ]
  }
}

List Conversation Sessions

Get all conversation sessions for the user.

curl "https://app.khoj.dev/api/chat/sessions" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

recent

boolean

default:"false"

If true, only returns the 8 most recent conversations

Response

[
  {
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "meeting-notes-discussion",
    "agent_name": "Khoj",
    "created": "2024-03-05 10:30:00",
    "updated": "2024-03-05 15:45:00"
  }
]

Create New Conversation

Start a new conversation session.

curl -X POST "https://app.khoj.dev/api/chat/sessions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_slug": "khoj"}'

agent_slug

string

Slug of the agent to use for this conversation

Delete Conversation

Delete a conversation and its history.

curl -X DELETE "https://app.khoj.dev/api/chat/history?conversation_id=CONV_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Set Conversation Title

Update the title of a conversation.

curl -X PATCH "https://app.khoj.dev/api/chat/title" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "CONV_ID",
    "title": "Project Planning Discussion"
  }'

Advanced Features

Include images in your messages:

import base64

with open("screenshot.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

data = {
    "q": "What's in this image?",
    "images": [f"data:image/png;base64,{image_data}"]
}

File Attachments

Attach files for context:

data = {
    "q": "Summarize this document",
    "files": [
        {
            "name": "report.txt",
            "content": "File content here..."
        }
    ]
}

Conversation Commands

Use special commands to control behavior:

/notes - Search only in your notes
/online - Search the web
/code - Run code to answer questions
/image - Generate an image
/diagram - Create a diagram
/research - Perform deep research with multiple iterations

curl -X POST https://app.khoj.dev/api/chat \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "/online What are the latest AI developments?"
  }'

Get Chat Options

Retrieve available conversation commands.

curl "https://app.khoj.dev/api/chat/options" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get Starter Questions

Get suggested questions to start a conversation.

curl "https://app.khoj.dev/api/chat/starters" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Text-to-Speech

Convert text responses to speech.

curl -X POST "https://app.khoj.dev/api/chat/speech" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, how can I help you today?"}' \
  --output speech.mp3

text

string

required

Text to convert to speech

Response: Audio file (MP3 format) Create a public link to share a conversation.

curl -X POST "https://app.khoj.dev/api/chat/share" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "CONV_ID"}'

Response

{
  "status": "ok",
  "url": "https://app.khoj.dev/share/abc123xyz"
}

Fork Public Conversation

Create your own copy of a public conversation.

curl -X POST "https://app.khoj.dev/api/chat/share/fork" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"public_conversation_slug": "abc123xyz"}'

Remove public access to a shared conversation.

curl -X DELETE "https://app.khoj.dev/api/chat/share?public_conversation_slug=abc123xyz" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

File Filters

Limit chat context to specific files.

Get File Filters

curl "https://app.khoj.dev/api/chat/conversation/file-filters/CONV_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Add File Filter

curl -X POST "https://app.khoj.dev/api/chat/conversation/file-filters" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "CONV_ID",
    "filename": "important-doc.md"
  }'

Remove File Filter

curl -X DELETE "https://app.khoj.dev/api/chat/conversation/file-filters" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "CONV_ID",
    "filename": "important-doc.md"
  }'

Rate Limits

Free tier: 20 messages per day
Premium tier: 75 messages per day for standard commands, higher limits for specific features

Some features have additional limits:

Image generation: 3 per day (free) / 30 per day (premium)
Online search: Limited per query
Code execution: Limited per query

Best Practices

Provide Context

Include relevant conversation history and file attachments for better responses.

Use Streaming

Enable streaming for better user experience with long responses.

Reuse Conversations

Continue existing conversations to maintain context across multiple turns.

Choose Right Agent

Use specialized agents for specific tasks when available.

Next Steps

Agents API

Create custom agents with specialized knowledge

Automations

Schedule recurring chat queries

Getting Started

Endpoints

Overview

Key Features

Start a Chat

Request Body

Response

Streaming Responses

Stream Event Types

Conversation Management

Get Conversation History

List Conversation Sessions

Create New Conversation

Delete Conversation

Set Conversation Title

Advanced Features

File Attachments

Conversation Commands

Get Chat Options

Get Starter Questions

Text-to-Speech

Fork Public Conversation

File Filters

Get File Filters

Add File Filter

Remove File Filter

Rate Limits

Best Practices

Next Steps

Agents API

Automations

Build docs developers (and LLMs) love

Getting Started

Endpoints

​Overview

​Key Features

​Start a Chat

​Request Body

​Response

​Streaming Responses

​Stream Event Types

​Conversation Management

​Get Conversation History

​List Conversation Sessions

​Create New Conversation

​Delete Conversation

​Set Conversation Title

​Advanced Features

​Multi-Modal Input

​File Attachments

​Conversation Commands

​Get Chat Options

​Get Starter Questions

​Text-to-Speech

​Sharing Conversations

​Create Public Share

​Fork Public Conversation

​Delete Public Share

​File Filters

​Get File Filters

​Add File Filter

​Remove File Filter

​Rate Limits

​Best Practices

​Next Steps

Agents API

Automations

Build docs developers (and LLMs) love

Overview

Key Features

Start a Chat

Request Body

Response

Streaming Responses

Stream Event Types

Conversation Management

Get Conversation History

List Conversation Sessions

Create New Conversation

Delete Conversation

Set Conversation Title

Advanced Features

Multi-Modal Input

File Attachments

Conversation Commands

Get Chat Options

Get Starter Questions

Text-to-Speech

Sharing Conversations

Create Public Share

Fork Public Conversation

Delete Public Share

File Filters

Get File Filters

Add File Filter

Remove File Filter

Rate Limits

Best Practices

Next Steps