Automations API

Overview

Automations allow you to schedule recurring queries that run automatically based on a cron schedule. Perfect for daily summaries, weekly reports, periodic research, or any recurring AI task.

Key Features

Cron Scheduling: Flexible scheduling using cron expressions
Email Delivery: Results sent to your email automatically
Dedicated Conversations: Each automation has its own conversation thread
Manual Triggers: Run automations on-demand in addition to scheduled times
Query Transformation: Khoj interprets and optimizes your query before execution

List Automations

Get all active automations for your account.

cURL

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

Python

import requests

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

Response

[
  {
    "id": "automation_123",
    "subject": "Daily Summary",
    "query": "Summarize important updates from my notes today",
    "scheduling_request": "Give me a daily summary of my notes",
    "schedule": "0 9 * * *",
    "schedule_description": "At 09:00 AM",
    "next_run_time": "2024-03-06T09:00:00Z",
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  {
    "id": "automation_456",
    "subject": "Weekly Research Digest",
    "query": "Find and summarize new AI research papers from this week",
    "scheduling_request": "Weekly digest of AI papers",
    "schedule": "0 18 * * 5",
    "schedule_description": "At 06:00 PM, only on Friday",
    "next_run_time": "2024-03-08T18:00:00Z",
    "conversation_id": "660e8400-e29b-41d4-a716-446655440001"
  }
]

string

Unique identifier for the automation

subject

string

Email subject line / automation title

query

string

The actual query that will be executed (may be transformed from original request)

scheduling_request

string

Original natural language scheduling request

schedule

string

Cron expression defining the schedule

schedule_description

string

Human-readable description of the schedule

next_run_time

string

ISO timestamp of next scheduled execution

conversation_id

string

Associated conversation thread ID

Create Automation

Schedule a new recurring automation.

cURL

curl -X POST "https://app.khoj.dev/api/automation" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Summarize my notes from today",
    "crontime": "0 9 * * *",
    "subject": "Daily Notes Summary",
    "timezone": "America/New_York"
  }'

Python

import requests

headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
automation_data = {
    "q": "Summarize my notes from today",
    "crontime": "0 9 * * *",
    "subject": "Daily Notes Summary",
    "timezone": "America/New_York"
}

response = requests.post(
    "https://app.khoj.dev/api/automation",
    headers=headers,
    json=automation_data
)
automation = response.json()

Request Parameters

string

required

The query to execute. Can be natural language - Khoj will interpret and optimize it.

crontime

string

required

Cron expression defining when to run (standard 5-field format)Examples:

0 9 * * * - Daily at 9:00 AM
0 18 * * 5 - Every Friday at 6:00 PM
30 14 1 * * - 1st of every month at 2:30 PM
0 */4 * * * - Every 4 hours

subject

string

Email subject / automation title. Auto-generated if not provided.

timezone

string

Timezone for schedule (e.g., “America/New_York”, “Europe/London”, “Asia/Tokyo”)

city

string

City for location-aware queries

region

string

Region/state for location-aware queries

country

string

Country for location-aware queries

Response

Returns the created automation object with all metadata.

Minute-level recurrence (e.g., */5 * * * * for “every 5 minutes”) is not supported. Minimum interval is hourly.

Update Automation

Modify an existing automation.

cURL

curl -X PUT "https://app.khoj.dev/api/automation?automation_id=automation_123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Summarize important updates and action items from today",
    "subject": "Daily Action Items",
    "crontime": "0 17 * * *",
    "timezone": "America/Los_Angeles"
  }'

automation_id

string

required

ID of the automation to update

string

required

Updated query

subject

string

required

Updated subject line

crontime

string

required

Updated cron schedule

timezone

string

Updated timezone

Response: Updated automation object

Delete Automation

Remove an automation.

cURL

curl -X DELETE "https://app.khoj.dev/api/automation?automation_id=automation_123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

automation_id

string

required

ID of the automation to delete

Response

{
  "id": "automation_123",
  "subject": "Daily Summary",
  "status": "deleted"
}

Trigger Automation Manually

Run an automation immediately without waiting for the schedule.

cURL

curl -X POST "https://app.khoj.dev/api/automation/trigger?automation_id=automation_123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

automation_id

string

required

ID of the automation to trigger

Response

Automation triggered

The automation runs asynchronously in the background. Results will be sent to your email.

Cron Schedule Format

Khoj uses standard 5-field cron expressions:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (0=Sunday)
│ │ │ │ │
* * * * *

Common Patterns

Pattern	Description	Example
`0 9 * * *`	Daily at 9 AM	Morning summary
`0 /6 * *`	Every 6 hours	Periodic check-ins
`0 9 * * 1`	Every Monday at 9 AM	Weekly planning
`0 18 * * 5`	Every Friday at 6 PM	Week wrap-up
`0 9 1 * *`	1st of month at 9 AM	Monthly report
`30 8 * * 1-5`	Weekdays at 8:30 AM	Workday briefing
`0 0 * * 0`	Every Sunday at midnight	Weekly reset

Special Characters

* - Any value
, - Value list separator (e.g., 1,15 = 1st and 15th)
- - Range (e.g., 1-5 = Monday through Friday)
/ - Step values (e.g., */2 = every 2 units)

Khoj replaces ? with * automatically. Both are equivalent.

Use Cases

Daily Summaries

{
  "q": "Summarize what I accomplished today based on my notes",
  "crontime": "0 18 * * *",
  "subject": "Daily Accomplishments"
}

Weekly Research Digest

{
  "q": "Find and summarize the most important AI research papers published this week",
  "crontime": "0 9 * * 1",
  "subject": "Weekly AI Research Digest"
}

Monthly Financial Review

{
  "q": "Analyze my financial notes from the past month and provide insights",
  "crontime": "0 10 1 * *",
  "subject": "Monthly Financial Review"
}

Morning Briefing

{
  "q": "What are my tasks and priorities for today? Check my calendar and notes.",
  "crontime": "0 7 * * 1-5",
  "subject": "Morning Briefing"
}

Project Status Updates

{
  "q": "Summarize progress on the Phoenix project based on recent notes and documents",
  "crontime": "0 16 * * 3",
  "subject": "Phoenix Project Update"
}

Automation Query Tips

Be Specific

Clear, specific queries produce better results. Instead of “summarize notes”, try “summarize meeting notes about the Q1 marketing campaign”.

Use Time References

Queries can reference relative times: “today”, “this week”, “last month”, “recent”, etc.

Include Context

Specify what types of content to focus on: “from my project notes”, “in my research folder”, etc.

Define Output Format

Request specific formats: “create a bullet list”, “write a brief summary”, “generate a detailed report”.

Use Commands

Include commands like /notes (search notes only) or /online (include web search).

How Automations Work

Schedule: Automation triggers at the scheduled cron time in your timezone
Query Execution: Khoj executes the query, searching your knowledge base and/or web
Response Generation: AI generates a comprehensive response with references
Email Delivery: Results are sent to your registered email address
Conversation Storage: The exchange is saved to the dedicated conversation thread

You can view past automation results in the conversation associated with each automation.

Error Handling

400 Bad Request - Missing Parameters

{
  "detail": "A query and crontime is required"
}

Ensure both q and crontime are provided.

400 Bad Request - Invalid Cron

{
  "detail": "Invalid crontime"
}

Check your cron expression syntax. Use a cron validator to verify.

400 Bad Request - Too Frequent

{
  "detail": "Minute level recurrence is unsupported. Please create a less frequent schedule."
}

Your schedule runs too frequently. Minimum interval is hourly.

403 Forbidden

{
  "detail": "Invalid automation"
}

Automation doesn’t exist or you don’t own it.

500 Internal Server Error

{
  "detail": "Unable to create automation. Ensure the automation doesn't already exist."
}

An automation with identical parameters may already exist.

Best Practices

Smart Scheduling

Schedule automations at times when results are most useful. Daily summaries work well end-of-day.

Descriptive Subjects

Use clear subject lines so you can identify automation emails easily.

Test First

Use manual trigger to test your query before scheduling.

Review Conversations

Check the conversation thread periodically to see automation history and refine queries.

Limitations

Minimum scheduling interval: 1 hour
Maximum automations per user: Varies by subscription tier
Automations use the default Khoj agent (you can’t specify custom agents yet)

Next Steps

Chat API

Learn about the chat capabilities used by automations

Agents API

Create specialized agents for different automation tasks

Getting Started

Endpoints

Automations API

Overview

Key Features

List Automations

Create Automation

Request Parameters

Response

Update Automation

Delete Automation

Trigger Automation Manually

Cron Schedule Format

Common Patterns

Special Characters

Use Cases

Daily Summaries

Weekly Research Digest

Monthly Financial Review

Morning Briefing

Project Status Updates

Automation Query Tips

How Automations Work

Error Handling

400 Bad Request - Missing Parameters

400 Bad Request - Invalid Cron

400 Bad Request - Too Frequent

403 Forbidden

500 Internal Server Error

Best Practices

Smart Scheduling

Descriptive Subjects

Test First

Review Conversations

Limitations

Next Steps

Chat API

Agents API

Build docs developers (and LLMs) love

Getting Started

Endpoints

​Overview

​Key Features

​List Automations

​Create Automation

​Request Parameters

​Response

​Update Automation

​Delete Automation

​Trigger Automation Manually

​Cron Schedule Format

​Common Patterns

​Special Characters

​Use Cases

​Daily Summaries

​Weekly Research Digest

​Monthly Financial Review

​Morning Briefing

​Project Status Updates

​Automation Query Tips

​How Automations Work

​Error Handling

​400 Bad Request - Missing Parameters

​400 Bad Request - Invalid Cron

​400 Bad Request - Too Frequent

​403 Forbidden

​500 Internal Server Error

​Best Practices

Smart Scheduling

Descriptive Subjects

Test First

Review Conversations

​Limitations

​Next Steps

Chat API

Agents API

Build docs developers (and LLMs) love

Overview

Key Features

List Automations

Create Automation

Request Parameters

Response

Update Automation

Delete Automation

Trigger Automation Manually

Cron Schedule Format

Common Patterns

Special Characters

Use Cases

Daily Summaries

Weekly Research Digest

Monthly Financial Review

Morning Briefing

Project Status Updates

Automation Query Tips

How Automations Work

Error Handling

400 Bad Request - Missing Parameters

400 Bad Request - Invalid Cron

400 Bad Request - Too Frequent

403 Forbidden

500 Internal Server Error

Best Practices

Limitations

Next Steps