kirha logo

Search API Quickstart

What is the Search API

The Kirha Search API lets agents query premium data sources through a unified endpoint. It is part of Kirha's Tool Planning and Micropayment infrastructure.

You can access the Search API directly via cURL or through the kirha TypeScript SDK. Both approaches support two integration modes:

  • Auto mode - submit a query, get a summarized response. No manual intervention required.
  • Plan mode - get a plan first, review providers and costs, then execute.

Both modes rely on deterministic planning. The same query yields the same plan.

Authentication

All Search 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,
  vertical: "crypto"
});

Include your key in the Authorization header:

Authorization: Bearer <your_api_key>

Submit a query and receive a summarized response based on real-time data from multiple providers.

const result = await kirha.search("What is the current bitcoin price?", {
  summarization: "kirha-flash",
  includeData: false,
});

console.log(result.data);
curl -X POST "https://api.kirha.com/chat/v1/search" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "What is the current bitcoin price?",
         "vertical_id": "crypto",
         "summarization": { "enable": true, "model": "kirha-flash" },
         "include_raw_data": false
      }'
{
  "id": "plan_OxTegmy5ZsfayxLr4g3Fv",
  "summary": "The current price of Bitcoin (BTC) is **$114,659**.\n\nHere are some additional details:\n\n*   **24h High:** $114,739\n*   **24h Low:** $111,764\n*   **Price Change (24h):** +$869.33 (+0.76%)\n*   **Market Cap:** $2,287,250,518,801\n*   **Market Cap Rank:** 1\n*   **All-Time High (ATH):** $124,128 (reached on 2025-08-14)\n*   **All-Time Low (ATL):** $67.81 (reached on 2013-07-06)\n\n*Last updated: 2025-08-22 14:20:42 UTC*"
}

Plan, review and execute

Submit a query and receive a detailed plan of which data providers will be queried. Review the plan before execution.

Get a plan for your query

const plan = await kirha.plan("What is the current bitcoin price?");

console.log(plan.id);     // "plan_OxTegmy5ZsfayxLr4g3Fv"
console.log(plan.steps);  // array of planned steps
curl -X POST "https://api.kirha.com/chat/v1/search/plan" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "What is the current bitcoin price?",
         "vertical_id": "crypto"
      }'

Review the plan, including data providers and costs

  {
    "id": "plan_OxTegmy5ZsfayxLr4g3Fv",
    "status": "pending_confirmation",
    "steps": [
      {
        "id": "step_kfhgLz9Pl68ctOK9jXfoC",
        "status": "pending",
        "tool_name": "coingecko_searchCoin",
        "parameters": {
          "limit": 1,
          "query": "Bitcoin"
        },
        "reasoning": "First, I need to find the CoinGecko ID for Bitcoin to use in subsequent calls."
      },
      {
        "id": "step_Q9J0ja2GygqDDfdA8g4do",
        "status": "pending",
        "tool_name": "coingecko_getCoinMarketData",
        "parameters": {
          "coinId": {
            "$fromStep": "step_kfhgLz9Pl68ctOK9jXfoC",
            "$outputKey": "coins.0.id"
          },
          "currency": "usd"
        },
        "reasoning": "Once I have the CoinGecko ID for Bitcoin, I can fetch its current market price in USD."
      }
    ]
  }

Execute the plan

const result = await plan.execute({
  summarization: "kirha-flash",
  includeData: false,
});

console.log(result.data);
curl -X POST "https://api.kirha.com/chat/v1/search/plan/run" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "plan_id": "plan_OxTegmy5ZsfayxLr4g3Fv",
         "summarization": { "enable": true, "model": "kirha-flash" },
         "include_raw_data": false
      }'
{
  "id": "plan_OxTegmy5ZsfayxLr4g3Fv",
  "summary": "The current price of Bitcoin (BTC) is **$114,659**.\n\nHere are some additional details:\n\n*   **24h High:** $114,739\n*   **24h Low:** $111,764\n*   **Price Change (24h):** +$869.33 (+0.76%)\n*   **Market Cap:** $2,287,250,518,801\n*   **Market Cap Rank:** 1\n*   **All-Time High (ATH):** $124,128 (reached on 2025-08-14)\n*   **All-Time Low (ATL):** $67.81 (reached on 2013-07-06)\n\n*Last updated: 2025-08-22 14:20:42 UTC*"
}

Configuration options

Summarization

Search API can return a concise summary of the aggregated data from multiple providers. Two models are available:

  • kirha - primary model, optimized for high-quality, context-aware responses. Best for complex queries requiring reasoning.
  • kirha-flash - faster, lightweight variant for low-latency use cases. Best for high-throughput applications.
const result = await kirha.search("What is the current bitcoin price?", {
  summarization: "kirha-flash",
  includeData: false,
});
curl -X POST "https://api.kirha.com/chat/v1/search" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "What is the current bitcoin price?",
         "vertical_id": "crypto",
         "summarization": { "enable": true, "model": "kirha-flash" },
         "include_raw_data": false
      }'

Raw data

By default, Search API returns raw data from the queried data providers. Set includeData to false to exclude it (or include_raw_data in cURL). Raw data is structured for LLM consumption and includes metadata such as context, timestamps, and URLs.

const result = await kirha.search("What is the current bitcoin price?", {
  includeData: true,
});

console.log(result.data);
curl -X POST "https://api.kirha.com/chat/v1/search" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "What is the current bitcoin price?",
         "vertical_id": "crypto",
         "include_raw_data": true
      }'
  {
    "id": "plan_OxTegmy5ZsfayxLr4g3Fv",
    "raw_data": [
      {
        "step_id": "step_y2veULUcHkE6qJyATW0q3",
        "tool_name": "coingecko_getCoinMarketData",
        "parameters": {
          "coinId": "bitcoin"
        },
        "output": {
          "context": "Market data for bitcoin in usd.",
          "coinId": "bitcoin",
          "currentPrice": 114781,
          "marketCap": 2287774637052,
          "name": "Bitcoin",
          "low24h": 111764,
          "symbol": "btc"
        }
      }
    ]
  }

Planning

When using /v1/search/plan, the response includes a detailed plan of providers and estimated costs.

For the /v1/search endpoint, set include_planning to true to get the executed plan in the response.

// Plan mode returns the plan directly
const plan = await kirha.plan("What is the current bitcoin price?");

// Auto mode with planning info included
const result = await kirha.search("What is the current bitcoin price?", {
  includePlanning: true,
});
curl -X POST "https://api.kirha.com/chat/v1/search/plan" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "What is the current bitcoin price?",
         "vertical_id": "crypto"
      }'

Timeout

Plans remain valid and executable for 5 minutes after creation. This allows agents to perform additional reasoning, let a human operator review the plan, or top up credits before execution.

After 5 minutes, the plan expires and must be regenerated.

Rate limits

The Search API is rate-limited to 20 requests per minute. If you need a higher quota, feel free to reach out with your use case at developers@kirha.com.

API Reference

/v1/search

Prop

Type

/v1/search/plan

Prop

Type

/v1/search/plan/run

Prop

Type

/v1/search POST

Next Page

On this page

What is the Search APIAuthenticationAuto mode (recommended)Plan, review and executeConfiguration optionsSummarizationRaw dataPlanningTimeoutRate limitsAPI Reference/v1/search/v1/search/plan/v1/search/plan/run