kirha logo

Search API Quickstart

What is Kirha Search API?

The Kirha Search API is the recommended way to integrate Kirha into your agent workflows. As part of Kirha’s Tool Planning and Micropayment infrastructure, it enables agents to query premium data sources via a unified API endpoint, designed for transparency and control.

Both endpoints rely on Kirha’s deterministic planning. The same query yields the same plan, ensuring reliability and auditability. The API offers two integration modes:

Authentication

All Search API requests require authentication with an API key. Include your key in the Authorization header:

Authorization: Bearer <your_api_key>

Keys can be managed in the Kirha dashboard. Create a project and generate an API key to get started.

Configuration options

Summarization

Search API can return a concise summary of the aggregated data from multiple providers. This is especially useful for agents that need a quick, high-level answer. It supports two models for summarization:

  • kirha is our primary model, optimized for high-quality, nuanced, and context-aware responses. It’s ideal for complex tasks that require reasoning, depth, or extended context. Currently based on OpenAi Gpt 5.
  • kirha-flash is a faster, lightweight variant designed for low-latency use cases. It’s best suited for high-throughput applications or situations where response time is critical. Currently based on Gemini 2.5 flash.
curl -X POST "https://api.kirha.ai/chat/v1/search" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "What is the current bitcoin price?",
         "vertical": "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*"
}

Raw data

By default, Search API returns only the raw data from the queried data providers. To remove the raw data in the response, set the include_raw_data parameter to false. Raw data are designed to be easily parsed by LLMs, and include relevant metadata such as context, timestamps, URLs.

curl -X POST "https://api.kirha.ai/chat/v1/search" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "What is the current bitcoin price?",
         "vertical": "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 the /v1/search/plan endpoint, the response includes a detailed plan outlining which data providers will be queried, along with estimated costs.

For the /v1/search endpoint, you can also get the executed plan by setting the include_planning parameter to true.

curl -X POST "https://api.kirha.ai/chat/v1/search/plan" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "What is the current bitcoin price?",
         "vertical": "crypto"
      }'
  {
    "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."
      }
    ]
  }

Timeout

Tool planning results remain valid and executable for 5 minutes after creation. For example, this delay allows agents to perform additional reasoning before execution, let a human operator review or approve the plan, or top up Kirha credits if needed.

After 5 minutes, the plan expires and a new plan must be generated.

Rate limits

The Search API is rate-limited to 20 requests per minute. If you need a higher quota, increased rate limits, or support for a new model, feel free to reach out to us with your use case.

API Reference

/v1/search

PropTypeDefault
query
string
-
vertical
string
-
summarization?
object
{ "enable": false, "model": "kirha" }
include_raw_data?
boolean
true
include_planning?
boolean
false

/v1/search/plan

PropTypeDefault
query
string
-
vertical
string
-

/v1/search/plan/run

PropTypeDefault
plan_id
string
-
summarization?
object
{ "enable": false, "model": "kirha" }
include_raw_data?
boolean
true
include_planning?
boolean
false

Kirha planning

Previous Page

/v1/searchPOST

Next Page