Search API Quickstart

KIODO_API_KEY="kiodo_live_..."

Authorization: Bearer $KIODO_API_KEY
Content-Type: application/json

import { Kiodo } from "kiodo";

const kiodo = new Kiodo({
  apiKey: process.env.KIODO_API_KEY
});

const results = await kiodo.search({
  query: "latest funding news for AI sales tools",
  type: "auto",
  numResults: 10,
  category: "news"
});

console.log(results.results);
console.log(results.usage);

curl https://api.kiodo.dev/v1/search \
  -H "Authorization: Bearer $KIODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest funding news for AI sales tools",
    "type": "auto",
    "numResults": 10,
    "category": "news"
  }'

{
  "object": "search.results",
  "results": [
    {
      "title": "Result title",
      "url": "https://example.com/article",
      "domain": "example.com",
      "text": "Result snippet"
    }
  ],
  "output": {
    "query": "latest funding news for AI sales tools",
    "mode": "auto",
    "filters": { "category": "news" },
    "topDomains": ["example.com"]
  },
  "usage": {
    "credits": 1,
    "balanceCredits": 1665,
    "cacheHit": false
  }
}

export KIODO_API_KEY="kiodo_live_or_mk_..."

curl https://api.kiodo.dev/v1/search \
  -H "Authorization: Bearer $KIODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best vector databases for production RAG",
    "type": "auto",
    "numResults": 5
  }'

curl https://api.kiodo.dev/v1/usage \
  -H "Authorization: Bearer $KIODO_API_KEY"

const usage = await kiodo.usage();

console.log(usage.balanceCredits);
console.log(usage.endpointUsage);

// Run from an authenticated dashboard session.
const response = await fetch("/api/dashboard/api-keys", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Production Search key",
    scope: "search:read"
  })
});

const { token, key } = await response.json();

// Run from an authenticated dashboard session.
const response = await fetch("/api/dashboard/credits/checkout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ credits: 10000 })
});

const { url } = await response.json();
window.location.href = url;

const visibility = await kiodo.aiVisibility.check({
  brand: "Acme",
  category: "payroll API",
  market: "us",
  competitors: ["Gusto", "Check"]
});

console.log(visibility.visibilityScore);
console.log(visibility.shareOfAnswer);

curl https://api.kiodo.dev/v1/ai-visibility/check \
  -H "Authorization: Bearer $KIODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Acme",
    "domain": "acme.com",
    "category": "payroll API",
    "competitors": ["Gusto", "Check", "Finch"],
    "market": "us",
    "language": "en",
    "limit": 25
  }'

{
  "object": "ai_visibility.check",
  "schemaVersion": "2026-05-ai-visibility-check-v1",
  "visibilityScore": 23.4,
  "shareOfAnswer": {
    "Acme": 0.18,
    "Gusto": 0.71,
    "Check": 0.42
  },
  "mentionedIn": {
    "total": 12,
    "byEngine": {
      "chatgpt": 12
    }
  },
  "topCitedSources": [],
  "opportunities": [],
  "confidence": 0.82,
  "dataFreshness": {
    "type": "aggregated",
    "cached": false,
    "asOf": "2026-05-20T00:00:00.000Z"
  },
  "usage": {
    "operationKey": "ai_visibility_check_small",
    "credits": 75,
    "balanceCredits": 1234,
    "cacheHit": false
  }
}

curl https://api.kiodo.dev/v1/contents \
  -H "Authorization: Bearer $KIODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com"],
    "maxCharacters": 12000,
    "mainText": true,
    "markdown": true,
    "livecrawl": { "type": "fallback" },
    "highlights": { "query": "pricing, product, traction" }
  }'

{
  "schemaVersion": "2026-05-contents-v1",
  "results": [
    {
      "success": true,
      "status": "ok",
      "title": "Example",
      "text": "...",
      "markdown": "...",
      "quality": {
        "score": 82,
        "label": "good",
        "warnings": []
      }
    }
  ]
}

curl https://api.kiodo.dev/v1/context \
  -H "Authorization: Bearer $KIODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best alternatives to Salesforce for small businesses",
    "mode": "balanced",
    "numResults": 5,
    "contents": {
      "highlights": true,
      "markdown": false,
      "maxCharacters": 6000
    }
  }'

{
  "schemaVersion": "2026-05-context-v1",
  "success": true,
  "status": "ok",
  "results": [
    {
      "title": "...",
      "url": "https://example.com",
      "snippet": "...",
      "content": {
        "success": true,
        "status": "ok",
        "text": "...",
        "highlights": ["..."],
        "quality": {
          "score": 84,
          "label": "good",
          "warnings": []
        }
      }
    }
  ]
}

curl https://api.kiodo.dev/v1/answer \
  -H "Authorization: Bearer $KIODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Which AI SDR tools raised funding in the last 90 days?",
    "type": "deep",
    "numResults": 8,
    "includeText": true,
    "systemPrompt": "Return concise market intelligence for a research team."
  }'

{
  "object": "usage.summary",
  "balanceCredits": 1665,
  "usedCredits": 42,
  "calls": 42,
  "metrics": {
    "cacheHitRate": 38,
    "contentCacheHitRate": 52,
    "contextPartialRate": 8,
    "contextFailureRate": 1
  },
  "endpointUsage": [],
  "quality": [],
  "recentRequests": []
}