Kirha Docs - Tools API Quickstart

What is the Tools API

The Tools API lets you list all available data provider tools for a given vertical and execute them directly with explicit parameters. This bypasses the planning engine entirely, giving you full control over 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 natural language query and want Kirha to determine the right tools automatically, use the Search API instead.

Authentication

All Tools 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>

List available tools

Retrieve all tools available for a given vertical:

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

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

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

Vertical-scoped

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

Each tool in the response includes an inputSchema and outputSchema that describe the expected parameters and response shape. Always follow these schemas strictly when calling a tool, as malformed inputs will be rejected.

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

Execute a tool

Call a specific tool with explicit parameters:

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

console.log(result);

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

{
  "context": "Search results for \"Avax\".",
  "coins":[
    {
      "id": "avalanche-2",
      "name": "Avalanche",
      "symbol": "AVAX",
      "marketCapRank": 29,
      "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"
    }
  ]
}

API Reference

GET /v1/tools

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

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

Prop

Type

POST /v1/tools/execute

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

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