Agents API

Overview

Agents in Khoj are customizable AI assistants with specific personalities, knowledge bases, and capabilities. You can create agents for different purposes like research, coding, writing, or domain-specific tasks.

Key Features

Custom Personalities: Define unique personas and communication styles
Specialized Knowledge: Attach specific files and documents
Tool Selection: Choose which input tools (search, web, code) and output modes (text, image) the agent can use
Privacy Levels: Control whether agents are private, public, or protected
Model Selection: Choose different chat models per agent

List All Agents

Get all agents accessible to the user.

cURL

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

Python

import requests

headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
response = requests.get(
    "https://app.khoj.dev/api/agents",
    headers=headers
)
agents = response.json()

Response

[
  {
    "slug": "khoj",
    "name": "Khoj",
    "persona": "You are Khoj, an advanced AI personal assistant...",
    "creator": null,
    "managed_by_admin": true,
    "color": "#7C3AED",
    "icon": "🦾",
    "privacy_level": "public",
    "chat_model": "gpt-4o-mini",
    "files": [],
    "input_tools": ["online", "notes", "webpage"],
    "output_modes": ["text", "image"]
  },
  {
    "slug": "research-assistant",
    "name": "Research Assistant",
    "persona": "You are a research assistant specializing in academic papers...",
    "creator": "[email protected]",
    "managed_by_admin": false,
    "color": "#3B82F6",
    "icon": "📚",
    "privacy_level": "private",
    "chat_model": "gpt-4o",
    "files": ["research-methods.pdf"],
    "input_tools": ["online", "notes"],
    "output_modes": ["text"]
  }
]

Get Agent by Slug

Retrieve details for a specific agent.

curl "https://app.khoj.dev/api/agents/research-assistant" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

agent_slug

string

required

Unique slug identifier for the agent

Get Agent for Conversation

Get the agent associated with a specific conversation.

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

conversation_id

string

required

Conversation ID to get the agent for

Response

{
  "slug": "research-assistant",
  "name": "Research Assistant",
  "persona": "You are a research assistant...",
  "creator": "[email protected]",
  "managed_by_admin": false,
  "color": "#3B82F6",
  "icon": "📚",
  "privacy_level": "private",
  "chat_model": "gpt-4o",
  "has_files": true,
  "input_tools": ["online", "notes"],
  "output_modes": ["text"],
  "is_creator": true,
  "is_hidden": false
}

Create Agent

Create a new custom agent.

cURL

curl -X POST "https://app.khoj.dev/api/agents" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Reviewer",
    "persona": "You are an experienced code reviewer who provides constructive feedback on code quality, best practices, and potential bugs.",
    "privacy_level": "private",
    "icon": "👨‍💻",
    "color": "#10B981",
    "chat_model": "gpt-4o-mini",
    "input_tools": ["online", "code"],
    "output_modes": ["text"],
    "files": []
  }'

Python

import requests

headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
agent_data = {
    "name": "Code Reviewer",
    "persona": "You are an experienced code reviewer...",
    "privacy_level": "private",
    "icon": "👨‍💻",
    "color": "#10B981",
    "chat_model": "gpt-4o-mini",
    "input_tools": ["online", "code"],
    "output_modes": ["text"],
    "files": []
}

response = requests.post(
    "https://app.khoj.dev/api/agents",
    headers=headers,
    json=agent_data
)
agent = response.json()

Request Body

name

string

required

Display name for the agent

persona

string

required

Detailed description of the agent’s personality, expertise, and behavior. This is the system prompt.

privacy_level

string

required

Agent visibility:

private - Only you can use this agent
public - Anyone can discover and use this agent
protected - Only people you share with can use

icon

string

required

Emoji icon for the agent (single emoji character)

color

string

required

Hex color code for the agent’s theme (e.g., “#7C3AED”)

chat_model

string

required

Chat model to use:

gpt-4o - Most capable (premium)
gpt-4o-mini - Fast and efficient
claude-3-5-sonnet-20241022 - Anthropic’s latest
gemini-2.0-flash-exp - Google’s fast model

files

string[]

default:"[]"

Array of filenames to include in the agent’s knowledge base

input_tools

string[]

default:"[]"

Tools the agent can use for gathering information:

online - Search the web
notes - Search user’s notes/documents
webpage - Read specific webpages
code - Execute code

output_modes

string[]

default:"[]"

Output formats the agent can generate:

text - Text responses
image - Generate images
diagram - Create diagrams

slug

string

Custom URL-friendly identifier. Auto-generated from name if not provided.

is_hidden

boolean

default:"false"

Whether the agent is hidden from public listing

Update Agent

Update an existing agent you created.

cURL

curl -X PATCH "https://app.khoj.dev/api/agents" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "code-reviewer",
    "name": "Senior Code Reviewer",
    "persona": "You are a senior code reviewer with 15 years of experience...",
    "privacy_level": "private",
    "icon": "👨‍💻",
    "color": "#10B981",
    "chat_model": "gpt-4o",
    "input_tools": ["online", "code", "notes"],
    "output_modes": ["text"],
    "files": ["coding-standards.md"]
  }'

slug

string

required

Slug of the agent to update

You can only update agents you created. All other parameters are the same as create.

Delete Agent

Delete an agent you created.

curl -X DELETE "https://app.khoj.dev/api/agents/code-reviewer" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

agent_slug

string

required

Slug of the agent to delete

Response

{
  "message": "Agent deleted."
}

Hidden Agents

Hidden agents are conversation-specific and not listed publicly. They’re useful for one-off custom configurations.

Create Hidden Agent

Create a hidden agent for a specific conversation.

curl -X POST "https://app.khoj.dev/api/agents/hidden?conversation_id=CONV_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "persona": "You are a debugging assistant...",
    "chat_model": "gpt-4o",
    "input_tools": ["code"],
    "output_modes": ["text"]
  }'

conversation_id

string

required

ID of conversation to attach this agent to

slug

string

Optional slug for the hidden agent

persona

string

Custom persona for this agent

chat_model

string

Chat model to use

input_tools

string[]

Available input tools

output_modes

string[]

Available output modes

Update Hidden Agent

curl -X PATCH "https://app.khoj.dev/api/agents/hidden" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "hidden-agent-slug",
    "persona": "Updated persona..."
  }'

Agent Configuration Options

Get available input tools and output modes for agent configuration.

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

Response

{
  "input_tools": {
    "online": "Search the web for up-to-date information",
    "notes": "Search through user's personal notes and documents",
    "webpage": "Read and extract content from specific webpages",
    "code": "Execute code to perform calculations or data analysis"
  },
  "output_modes": {
    "text": "Generate text responses",
    "image": "Create images using AI image generation",
    "diagram": "Create diagrams and flowcharts"
  }
}

Use Cases

Research Assistant

{
  "name": "Research Assistant",
  "persona": "You are a research assistant specialized in academic literature. You help users find relevant papers, summarize research, and identify key findings. Always cite sources and maintain academic rigor.",
  "input_tools": ["online", "notes"],
  "output_modes": ["text"],
  "files": ["research-methodology.pdf"]
}

Creative Writer

{
  "name": "Creative Writer",
  "persona": "You are a creative writing assistant who helps with storytelling, character development, and narrative structure. You provide constructive feedback and creative suggestions.",
  "input_tools": ["notes"],
  "output_modes": ["text"],
  "files": ["writing-guides.md", "story-templates.md"]
}

Code Assistant

{
  "name": "Code Assistant",
  "persona": "You are an expert programming assistant proficient in multiple languages. You help with code review, debugging, optimization, and explaining complex code concepts.",
  "input_tools": ["online", "code", "notes"],
  "output_modes": ["text"],
  "files": ["coding-standards.md"]
}

Visual Designer

{
  "name": "Visual Designer",
  "persona": "You are a visual design assistant who helps create images, illustrations, and visual concepts. You understand design principles, color theory, and composition.",
  "input_tools": ["online"],
  "output_modes": ["text", "image", "diagram"]
}

Best Practices

Clear Personas

Write clear, detailed personas that define the agent’s expertise, tone, and limitations.

Relevant Files

Attach only relevant files. Too many files can dilute the agent’s focus.

Tool Selection

Only enable tools the agent actually needs. Fewer tools = more focused behavior.

Test Thoroughly

Test your agent with various queries to ensure it behaves as expected.

Iterate

Refine the persona and settings based on actual usage and feedback.

Privacy Levels Explained

Private
Public
Protected

Only you can see and use the agent
Perfect for personal assistants with sensitive context
Not listed in public agent directory

Error Handling

400 Bad Request

{
  "error": "Agent with name code-reviewer already exists"
}

Agent with that slug already exists. Choose a different name/slug.

404 Not Found

{
  "error": "Agent with name xyz not found."
}

Agent doesn’t exist or you don’t have access to it.

Next Steps

Chat API

Use agents in conversations

Automations

Create scheduled tasks with agents

Getting Started

Endpoints

Overview

Key Features

List All Agents

Get Agent by Slug

Get Agent for Conversation

Create Agent

Request Body

Update Agent

Delete Agent

Hidden Agents

Create Hidden Agent

Update Hidden Agent

Agent Configuration Options

Use Cases

Research Assistant

Creative Writer

Code Assistant

Visual Designer

Best Practices

Privacy Levels Explained

Error Handling

400 Bad Request

404 Not Found

Next Steps

Chat API

Automations

Build docs developers (and LLMs) love

Getting Started

Endpoints

​Overview

​Key Features

​List All Agents

​Get Agent by Slug

​Get Agent for Conversation

​Create Agent

​Request Body

​Update Agent

​Delete Agent

​Hidden Agents

​Create Hidden Agent

​Update Hidden Agent

​Agent Configuration Options

​Use Cases

​Research Assistant

​Creative Writer

​Code Assistant

​Visual Designer

​Best Practices

​Privacy Levels Explained

​Error Handling

​400 Bad Request

​404 Not Found

​Next Steps

Chat API

Automations

Build docs developers (and LLMs) love

Overview

Key Features

List All Agents

Get Agent by Slug

Get Agent for Conversation

Create Agent

Request Body

Update Agent

Delete Agent

Hidden Agents

Create Hidden Agent

Update Hidden Agent

Agent Configuration Options

Use Cases

Research Assistant

Creative Writer

Code Assistant

Visual Designer

Best Practices

Privacy Levels Explained

Error Handling

400 Bad Request

404 Not Found

Next Steps