KIRHA Docs - Tools API Quickstart

What is the Tools API

The Tools API lists the data provider tools of a vertical and runs one of them with the parameters you choose. It skips the planner: you decide which provider is called and how.

Use the Tools API when you:

Already know which tool and parameters you need
Want to skip the planning step for your own orchestration logic
Need to call a single provider in isolation

Prefer Search API for most use cases

If you have a question in plain language and want KIRHA to pick the right tools, use the Search API instead.

Authentication

All Tools API requests need an API key. Create one at app.kirha.com/api-keys.

Pass it when you create the client:

import { Kirha } from "kirha";

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

Send it in the Authorization header. The Bearer prefix is optional:

Authorization: Bearer <your_api_key>

Send it in the Authorization header:

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['KIRHA_API_KEY']}"}

List available tools

List the tools of a vertical. The vertical is required here:

const tools = await kirha.tools({ focus: "crypto" });

for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
}

curl -X GET "https://api.kirha.com/tools/v1?vertical_id=crypto" \
     -H "Authorization: Bearer <your_api_key>"

tools = requests.get(
    "https://api.kirha.com/tools/v1",
    headers=headers,
    params={"vertical_id": "crypto"},
).json()

for tool in tools:
    print(f"{tool['name']}: {tool['description']}")

[
  {
    "id": "46100a94-d33f-4a7a-ba3a-d2ce548643bd",
    "name": "coingecko_searchCoin",
    "description": "Search for coins listed on CoinGecko by name or symbol.",
    "input_schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "limit": { "default": 1, "maximum": 10, "minimum": 1, "type": "number" },
        "query": { "type": "string" }
      },
      "required": ["query"]
    },
    "output_schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "context": { "type": "string" },
        "coins": { "type": "array", "items": { "type": "object" } }
      },
      "required": ["context", "coins"]
    }
  }
]

Vertical-scoped

Each vertical is a domain-specific collection of tools and providers. Browse them on the Providers Graph, or through the Discovery portal if you are an agent.

Each tool comes with an input_schema and an output_schema that describe its parameters and its response. Follow the input schema strictly: malformed inputs are rejected.

Each tool execution consumes credits. You can track usage on the Dashboard.

Execute a tool

Call a tool with explicit parameters:

const result = await kirha.executeTool("coingecko_searchCoin", {
  query: "avax",
  limit: 1,
});

console.log(result.output);

curl -X POST "https://api.kirha.com/tools/v1/execute" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "tool_name": "coingecko_searchCoin",
         "input": {
           "query": "avax",
           "limit": 1
         }
      }'

result = requests.post(
    "https://api.kirha.com/tools/v1/execute",
    headers=headers,
    json={
        "tool_name": "coingecko_searchCoin",
        "input": {"query": "avax", "limit": 1},
    },
).json()

print(result["output"])

{
  "tool_name": "coingecko_searchCoin",
  "output": {
    "context": "Search results for \"avax\".",
    "coins": [
      {
        "id": "avalanche-2",
        "name": "Avalanche",
        "symbol": "AVAX",
        "marketCapRank": 26,
        "thumbnailUrl": "https://coin-images.coingecko.com/coins/images/12559/thumb/Avalanche_Circle_RedWhite_Trans.png",
        "imageUrl": "https://coin-images.coingecko.com/coins/images/12559/large/Avalanche_Circle_RedWhite_Trans.png"
      }
    ]
  },
  "is_error": false,
  "usage": { "estimated": 1, "consumed": 1 }
}

Rate limits

Each Tools API route is limited to 120 requests per minute per organization. Over the limit, the API answers 429 with a Retry-After header.

API Reference

GET /tools/v1

const tools = await kirha.tools({ focus: "crypto" });

curl -X GET "https://api.kirha.com/tools/v1?vertical_id=crypto" \
     -H "Authorization: Bearer <your_api_key>"

tools = requests.get(
    "https://api.kirha.com/tools/v1",
    headers=headers,
    params={"vertical_id": "crypto"},
).json()

Prop

Type

POST /tools/v1/execute

const result = await kirha.executeTool("coingecko_searchCoin", {
  query: "avax",
  limit: 1,
});

curl -X POST "https://api.kirha.com/tools/v1/execute" \
     -H "Authorization: Bearer <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
         "tool_name": "coingecko_searchCoin",
         "input": { "query": "avax", "limit": 1 }
      }'

result = requests.post(
    "https://api.kirha.com/tools/v1/execute",
    headers=headers,
    json={"tool_name": "coingecko_searchCoin", "input": {"query": "avax", "limit": 1}},
).json()

Prop

Type

Tools API Quickstart

On this page