Kirha Docs - Tasks API Quickstart

What is the Tasks API

The Tasks API lets you create asynchronous research tasks that search across multiple verticals, validate findings with multiple agents, and retry failed steps automatically. See the SDK Tasks page for a full comparison with Search and the task lifecycle.

Prefer Search API for quick lookups

If you have a straightforward query targeting a single vertical and need results immediately, use the Search API instead.

Authentication

All Tasks API requests require an API key. Get yours from the Kirha Dashboard.

Pass it when initializing the client:

import { Kirha } from "kirha";

const kirha = new Kirha({
  apiKey: process.env.KIRHA_API_KEY,
});

Include your key in the Authorization header:

Authorization: Bearer <your_api_key>

Create a task

Submit a research query to create a new task:

const task = await kirha.task(
  "Compare the AI strategies of Google, Microsoft, and Meta",
  { instruction: "Focus on 2024-2025 developments" }
);

console.log("Task created:", task.id);

curl -X POST "https://api.kirha.com/chat/v1/tasks" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "Compare the AI strategies of Google, Microsoft, and Meta",
         "instruction": "Focus on 2024-2025 developments"
      }'

{
  "id": "task_abc123",
  "status": "Queued"
}

Poll for results

Check the task status and retrieve results once complete:

import { TaskStatus } from "kirha";

const result = await task.wait();

if (result.status === TaskStatus.Completed) {
  console.log("Result:", result.result);
} else {
  console.log("Error:", result.error);
}

curl -X GET "https://api.kirha.com/chat/v1/tasks/<task_id>" \
     -H "Authorization: Bearer <your_api_key>"

{
  "id": "task_abc123",
  "status": "Completed",
  "query": "Compare the AI strategies of Google, Microsoft, and Meta",
  "instruction": "Focus on 2024-2025 developments",
  "result": "Google has focused on...",
  "error": null,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:32:15Z"
}

API Reference

POST /v1/tasks

const task = await kirha.task(
  "Compare the AI strategies of Google, Microsoft, and Meta",
  { instruction: "Focus on 2024-2025 developments" }
);

curl -X POST "https://api.kirha.com/chat/v1/tasks" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "Compare the AI strategies of Google, Microsoft, and Meta",
         "instruction": "Focus on 2024-2025 developments"
      }'

Prop

Type

GET /v1/tasks/:taskId

const result = await task.wait();

curl -X GET "https://api.kirha.com/chat/v1/tasks/<task_id>" \
     -H "Authorization: Bearer <your_api_key>"

Prop

Type

GET /v1/tasks/:taskId/status

// Handled automatically by task.wait()

curl -X GET "https://api.kirha.com/chat/v1/tasks/<task_id>/status" \
     -H "Authorization: Bearer <your_api_key>"

Prop

Type

GET /v1/tasks/:taskId/result

// Included in the task.wait() response

curl -X GET "https://api.kirha.com/chat/v1/tasks/<task_id>/result" \
     -H "Authorization: Bearer <your_api_key>"

Prop

Type

Tasks API Quickstart

On this page