Build with Kendr using one scoped API key.

Connect a harness

Kendr speaks the OpenAI and Anthropic wire formats, so most agents, IDEs, and SDKs connect by pointing their base URL at https://kendr.org and pasting one scoped key. Use model: "auto" to let Intelligent Auto pick the best route per request — harness-supplied model names outside the kc-* catalog are auto-routed the same way. Paste the key you saved at creation in place of <YOUR_KEY> below — full keys are never shown again.

export ANTHROPIC_BASE_URL=https://kendr.org
export ANTHROPIC_AUTH_TOKEN=<YOUR_KEY>
claude

from openai import OpenAI

client = OpenAI(base_url="https://kendr.org/v1", api_key="<YOUR_KEY>")
resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(resp.choices[0].message.content)

curl https://kendr.org/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Say hi in five words."}]}'

# Cursor -> Settings -> Models -> API keys
#   OpenAI API key:     <YOUR_KEY>
#   Override base URL:  https://kendr.org/v1
# Then pick any model and send a chat message.

import anthropic

client = anthropic.Anthropic(base_url="https://kendr.org", auth_token="<YOUR_KEY>")
msg = client.messages.create(
    model="auto", max_tokens=64,
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(msg.content)

// Works with agents that accept a custom OpenAI-compatible provider
// (chat-completions API mode). Keep the key in an environment variable.
{
  "providers": {
    "kendr": {
      "baseUrl": "https://kendr.org/v1",
      "api": "openai-completions",
      "apiKey": "$KENDR_KEY",
      "models": [{ "id": "auto", "name": "Kendr Intelligent Auto" }]
    }
  }
}

// shell
export KENDR_KEY=<YOUR_KEY>

Frontier models through Kendr Cloud

The model gateway accepts Authorization: Bearer kndr_live_... and exposes the model aliases currently available to your Kendr account. Existing desktop clients can keep using /api/v1/llm/*; new integrations can use the standard /v1/* routes.

curl https://kendr.org/v1/chat/completions \
  -H "Authorization: Bearer kndr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-request-001" \
  -d '{
    "model": "kc-intelligent",
    "web_search": true,
    "messages": [{"role": "user", "content": "Summarize this decision."}]
  }'

Text model aliases can stream responses and can use web search when the route and account configuration support it. Omit web_search to let Kendr decide from the current request, set it to true to request current context, or set it to false to prohibit search. Idempotency-Key is optional on /v1/* requests — one is generated per request when absent, and supplying your own stable key makes retries replay the settled result instead of charging again. Successful responses include the final Kendr usage record.

Use Optimized mode through the API

Add an optimization policy to any Normal model or kc-intelligent request. For most production integrations, use mode: "balanced", engine: "auto", and allow_lossy_context: true. This lets Kendr reduce eligible earlier context while protecting system instructions, the latest user request, code, commands, diffs, URLs, schemas, identifiers, numbers, and exact artifacts.

Recommended curl request

curl https://kendr.org/v1/responses \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Idempotency-Key: optimizer-request-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kc-intelligent",
    "messages": [
      {"role": "user", "content": "Earlier detailed context..."},
      {"role": "assistant", "content": "Earlier answer..."},
      {"role": "user", "content": "Review the implementation and propose a safe patch."}
    ],
    "optimization": {
      "profile": "code",
      "mode": "balanced",
      "engine": "auto",
      "allow_lossy_context": true
    }
  }'

JavaScript

const response = await fetch("https://kendr.org/v1/responses", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KENDR_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "kc-intelligent",
    input: "Summarize the relevant decisions in this long project context.",
    optimization: {
      profile: "general",
      mode: "balanced",
      engine: "auto",
      allow_lossy_context: true
    }
  })
});

if (!response.ok) throw new Error(`Kendr request failed: ${response.status}`);
const result = await response.json();
console.log(result.output_text);
console.log(result.kendr_usage.credits_charged_micros);
console.log(result.kendr_optimization?.estimated_credits_saved_micros ?? 0);

Python

import os
import uuid
import requests

response = requests.post(
    "https://kendr.org/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['KENDR_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "kc-intelligent",
        "input": "Summarize the relevant decisions in this long project context.",
        "optimization": {
            "profile": "research",
            "mode": "balanced",
            "engine": "auto",
            "allow_lossy_context": True,
        },
    },
    timeout=180,
)
response.raise_for_status()
result = response.json()
print(result["output_text"])
print(result.get("kendr_optimization", {}))

Choose a mode

Legacy auto and safe values are still accepted and treated as balanced; without allow_lossy_context the balanced mode applies only lossless and reversible strategies, which matches the old safe behavior.

Profiles are general, code, and research. Use engine: "auto" unless you are testing a specific engine. extractive is the built-in relevance-based compressor and deterministic never performs semantic compression. Additional engine values are reserved for server-controlled experiments and always fall back safely.

Read the optimization receipt

{
  "kendr_usage": {
    "input_tokens": 1200,
    "output_tokens": 180,
    "credits_charged_micros": 180000
  },
  "kendr_optimization": {
    "enabled": true,
    "requested_mode": "balanced",
    "resolved_mode": "balanced",
    "engine": "extractive",
    "original_input_tokens_estimated": 1800,
    "optimized_input_tokens_estimated": 1200,
    "estimated_input_tokens_avoided": 600,
    "estimated_credits_saved_micros": 40000,
    "estimated_credits_without_optimization_micros": 220000,
    "quality_guard": {"passed": true, "checks": ["latest_user_request_preserved"], "violations": []},
    "shadow": false
  }
}

• kendr_usage.credits_charged_micros is the authoritative settled charge. Divide microcredits by 1,000,000 to display Kendr credits.
• estimated_credits_saved_micros is the rate-card-priced counterfactual saving from estimated avoided input tokens. Do not subtract it again; the settled charge already uses the optimized provider request.
• estimated_credits_without_optimization_micros is the comparable estimated charge without that input reduction.
• shadow: true means the deployment is running a preview-only evaluation. The provider received the original request, so no saving was applied.
• A zero saving is valid for short requests, protected content, structured-output/tool contracts, rejected quality checks, or unavailable semantic engines. Check fallback_reason, skipped_strategies, and quality_guard.violations.

Streaming

Send the same optimization object with stream: true. The final done event contains settled usage and the complete kendr_optimization receipt; token deltas do not contain billing information. Use /api/v1/llm/responses when you need Kendr-native named SSE events.

Model request fields

Use the same fields across /v1/responses, /v1/chat/completions, /v1/messages, and /api/v1/llm/responses where the compatibility format allows them.

Use web search with models

Text aliases expose web_search in the model catalog when the capability is available. Kendr supports provider-native web search on compatible routes and a managed cross-provider web-search gateway when configured.

curl -N https://kendr.org/v1/responses \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Idempotency-Key: web-search-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kc-intelligent",
    "input": "What changed in the web search provider landscape today?",
    "web_search": true,
    "stream": true
  }'

• Use web_search: true to request current web grounding.
• Use web_search: false for private/offline prompts that must not use web search.
• Use metadata.require_web_search: true only when the request should fail rather than answer without web search.
• When an answer uses web results, show source URLs returned in the model output or cited context.

Call remote MCP tools

Kendr tool calling is server-executed. You attach a registered MCP server to a request; Kendr injects the server URL and its encrypted authorization on the backend, the model calls the MCP tools during generation, and you receive only the final assistant text. There is no client-side function-calling loop: the API never returns a pending tool call for your code to execute, and it has no endpoint for submitting tool results back.

1. Register the server once

Create the server under your account with POST /api/me/mcp-servers (or the MCP servers page in the web app). Registration is a signed-in account action: authenticate with the X-Kendr-Session token from app login, the browser session cookie, or an OAuth token carrying the app scope. API keys cannot manage MCP servers — they only invoke models. The URL must be public HTTPS without embedded credentials, and the server must be marked trusted before it can be enabled. The optional authorization token is stored encrypted (AES-256-GCM) and is never returned by any API.

curl https://kendr.org/api/me/mcp-servers \
  -H "X-Kendr-Session: $KENDR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team docs",
    "server_label": "team-docs",
    "server_url": "https://mcp.example.com/mcp",
    "description": "Internal documentation search",
    "authorization": "Bearer mcp-token-...",
    "allowed_tools": ["search_docs", "read_page"],
    "enabled": true,
    "trusted": true
  }'

The response includes the generated id (mcp_...) you will reference in model requests. allowed_tools optionally restricts which MCP tools the model may call.

2. Reference it in a model request

curl https://kendr.org/v1/responses \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Idempotency-Key: mcp-demo-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kc-intelligent",
    "input": "Search the team docs for the deployment runbook and summarize it.",
    "conversation_id": "support-thread-8841",
    "tools": [
      { "type": "kendr_mcp", "server_id": "mcp_1f2e3d4c5b6a" }
    ]
  }'

Rules and limits

• The server must be enabled and trusted and belong to the authenticated account, otherwise the request fails with 400 "MCP server ... is unavailable, disabled, or not trusted." The rejection happens before any credits are reserved.
• MCP tools require an OpenAI Responses route. With kc-intelligent, routing automatically restricts candidates to compatible routes; with a Normal alias on an incompatible route the request fails with 400 "The selected model route does not support remote MCP tools. Choose an OpenAI Responses model."
• At most 8 MCP servers can be activated per request.
• Requests that declare tools do not stream token deltas; the response is delivered when generation completes.
• Provider-native tool declarations (for example OpenAI function tools) are forwarded to compatible routes, but any unexecuted tool call the model emits is not returned; if a model answers only with a tool call, Intelligent Auto treats the output as incomplete and no credits are charged.

Know which credential belongs where

Kendr has three credential layers. They solve different problems and are intentionally not interchangeable.

Use OpenAI, Anthropic, or native HTTPS clients

import OpenAI from "openai";
import crypto from "node:crypto";

const client = new OpenAI({
  apiKey: process.env.KENDR_API_KEY,
  baseURL: "https://kendr.org/v1"
});

const response = await client.responses.create({
  model: "kc-intelligent",
  input: "Plan a safe database migration."
}, {
  headers: { "Idempotency-Key": crypto.randomUUID() }
});

console.log(response.output_text);
console.log(response.kendr_usage);

import os
import uuid
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KENDR_API_KEY"],
    base_url="https://kendr.org/v1",
)

response = client.responses.create(
    model="kc-intelligent",
    input="Plan a safe database migration.",
    extra_headers={"Idempotency-Key": str(uuid.uuid4())},
)

print(response.output_text)

curl https://kendr.org/v1/messages \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Idempotency-Key: messages-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kc-intelligent",
    "max_tokens": 1200,
    "messages": [{"role":"user","content":"Review this plan."}]
  }'

curl -N https://kendr.org/v1/chat/completions \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Idempotency-Key: stream-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kc-intelligent",
    "stream": true,
    "messages": [{"role":"user","content":"Explain the rollout."}]
  }'

Integration rules

Quickstart flow

Auth headers accepted by the query route

Query request body

{
  "surface": "google_search",
  "query": "best llm observability tools",
  "params": {
    "gl": "us",
    "hl": "en",
    "page": 1
  }
}

Query examples

Kendr is a plain HTTPS and JSON API. The same request contract works from JavaScript, Python, .NET, Java, and Go, so you can use whichever runtime already exists in your stack.

curl https://kendr.org/api/v1/query \
  -X POST \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "surface": "google_search",
    "query": "best llm observability tools",
    "params": {
      "gl": "us",
      "hl": "en",
      "page": 1
    }
  }'

curl https://kendr.org/api/v1/query \
  -X POST \
  -H "X-Kendr-Session: $KENDR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "surface": "google_maps",
    "query": "coworking spaces in austin",
    "params": {
      "gl": "us",
      "hl": "en"
    }
  }'

curl https://kendr.org/api/v1/query \
  -X POST \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "surface": "google_search",
    "query": "best llm observability tools",
    "params": {
      "gl": "us",
      "hl": "en",
      "page": 1
    }
  }'

const response = await fetch('https://kendr.org/api/v1/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.KENDR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    surface: 'google_search',
    query: 'best llm observability tools',
    params: { gl: 'us', hl: 'en', page: 1 }
  })
});

const payload = await response.json();
console.log(payload.data, payload.remaining_credits);

import os
import requests

response = requests.post(
    'https://kendr.org/api/v1/query',
    headers={
        'Authorization': f"Bearer {os.environ['KENDR_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'surface': 'google_search',
        'query': 'best llm observability tools',
        'params': {'gl': 'us', 'hl': 'en', 'page': 1},
    },
    timeout=30,
)

payload = response.json()
print(payload['data'])
print(payload['remaining_credits'])

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KENDR_API_KEY"));

var body = new
{
    surface = "google_search",
    query = "best llm observability tools",
    @params = new
    {
        gl = "us",
        hl = "en",
        page = 1
    }
};

using var response = await client.PostAsync(
    "https://kendr.org/api/v1/query",
    new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json")
);

response.EnsureSuccessStatusCode();

using var stream = await response.Content.ReadAsStreamAsync();
var payload = await JsonSerializer.DeserializeAsync(stream);

Console.WriteLine(payload.GetProperty("data").ToString());
Console.WriteLine(payload.GetProperty("remaining_credits").GetInt32());

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

String requestBody = """
{
  "surface": "google_search",
  "query": "best llm observability tools",
  "params": {
    "gl": "us",
    "hl": "en",
    "page": 1
  }
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://kendr.org/api/v1/query"))
    .header("Authorization", "Bearer " + System.getenv("KENDR_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(requestBody))
    .build();

HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    body := map[string]any{
        "surface": "google_search",
        "query": "best llm observability tools",
        "params": map[string]any{
            "gl": "us",
            "hl": "en",
            "page": 1,
        },
    }

    rawBody, err := json.Marshal(body)
    if err != nil {
        panic(err)
    }

    req, err := http.NewRequest(http.MethodPost, "https://kendr.org/api/v1/query", bytes.NewReader(rawBody))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Authorization", "Bearer "+os.Getenv("KENDR_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var payload map[string]any
    if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
        panic(err)
    }

    fmt.Println(payload["data"])
    fmt.Println(payload["remaining_credits"])
}

Official helper clients

Kendr currently publishes helper clients for JavaScript and Python. Use these when you want a thinner call surface around the raw HTTP routes, or call the HTTPS endpoints directly from any other runtime.

import { KendrClient } from './sdk/javascript/index.js';

const client = new KendrClient({
  apiKey: process.env.KENDR_API_KEY,
  baseUrl: 'https://kendr.org'
});

const response = await client.query({
  surface: 'google_search',
  query: 'best llm observability tools',
  params: { gl: 'us', hl: 'en', page: 1 }
});

console.log(response.data);

from kendr import KendrClient

client = KendrClient(
    api_key='YOUR_KENDR_API_KEY',
    base_url='https://kendr.org',
)

response = client.query(
    surface='google_search',
    query='best llm observability tools',
    params={'gl': 'us', 'hl': 'en', 'page': 1},
)

print(response['data'])

Fetch surfaces, packages, and current credits

Use the public catalog to discover what is available, then use the customer dashboard to read the live wallet balance and package state for the authenticated user.

curl https://kendr.org/api/catalog

curl https://kendr.org/api/me/dashboard \
  -H "X-Kendr-Session: $KENDR_SESSION"

Create and use API keys

API keys are customer-scoped credentials. They are created after a customer logs in through a browser session, app session, or OAuth bearer token, and the raw key is returned only once.

curl https://kendr.org/api/me/api-keys \
  -X POST \
  -H "X-Kendr-Session: $KENDR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Production"
  }'

curl https://kendr.org/api/me/api-keys \
  -H "X-Kendr-Session: $KENDR_SESSION"

Successful response and errors

{
  "ok": true,
  "surface": "google_search",
  "credits_charged": 1,
  "remaining_credits": 249,
  "data": {
    "results": [],
    "answer": "",
    "citations": []
  },
  "normalized": {
    "results": [],
    "answer": "",
    "citations": []
  }
}

Read the model response envelope

Successful model responses add three Kendr blocks next to the compatibility-format fields. A trimmed /v1/responses result:

{
  "id": "0887c41b-5285-409d-ad04-b900b9a258c3",
  "model": "kc-intelligent",
  "status": "completed",
  "output_text": "Hello! How can I help?",
  "usage": { "input_tokens": 36, "output_tokens": 25, "total_tokens": 61 },
  "kendr_usage": {
    "credits_charged": "0.01165",
    "credits_charged_micros": 11650,
    "remaining_credits": "49886.925505",
    "request_id": "0887c41b-5285-409d-ad04-b900b9a258c3",
    "pricing_version": "cloud-v1"
  },
  "kendr_routing": {
    "selected_model_alias": "kc-llama-4-scout",
    "source": "router_model",
    "task_category": "flash",
    "reason_code": "trivial_greeting_cheapest_fast",
    "confidence": "0.95",
    "tools": []
  },
  "kendr_optimization": {
    "enabled": true,
    "requested_mode": "balanced",
    "resolved_mode": "balanced",
    "engine": "extractive",
    "estimated_input_tokens_avoided": 24,
    "estimated_credits_saved_micros": 4000,
    "estimated_credits_without_optimization_micros": 15650,
    "shadow": false
  }
}

Keep API keys out of client code

Store Kendr API keys in a server-side secret manager or protected environment variable. Never place a live key in browser JavaScript, a mobile bundle, a public repository, logs, analytics events, or support screenshots.

# Local development only
KENDR_API_KEY=kndr_live_replace_with_your_key

# Application configuration
KENDR_BASE_URL=https://kendr.org/v1
KENDR_MODEL=kc-intelligent

• Create separate keys for development and production so one environment can be revoked without interrupting the other.
• Use the narrowest scopes your integration needs. Model listing needs models:read; generation needs models:invoke; usage reads need usage:read.
• Rotate a key by creating its replacement, updating callers, confirming traffic on the new key, and then revoking the old key.
• Proxy browser and mobile requests through your backend when your product cannot safely hold a server credential.

Kendr configuration reference

Use environment variables or protected deployment secrets for service configuration. Client applications normally need only KENDR_API_KEY, KENDR_BASE_URL, and the selected model alias.

Retries, timeouts, and idempotency

Idempotency-Key is optional — Kendr generates one per request when absent. Supplying your own key is recommended for production retry safety: reuse the same key only when retrying the same logical operation, and create a new key for a new user request.

Handle streaming correctly

• Send stream: true and keep the HTTP connection open for server-sent events.
• Parse complete SSE events rather than treating arbitrary network chunks as complete JSON messages.
• Handle start, status, delta, done, and error events where present.
• Accumulate text deltas for display, but treat the terminal event as the authoritative completion and usage record.
• If the connection fails before completion, retry the same logical request with the same idempotency key.
• Do not assume every model emits identical timing or intermediate events; depend only on the compatible event fields you use.

Track usage without recording sensitive prompts

Record your own request identifier, idempotency key, selected Kendr alias, status, latency, token totals, and returned credit charge. Avoid logging authorization headers or full prompts unless your own privacy policy explicitly requires and protects that data.

curl https://kendr.org/api/me/billing/summary \
  -H "X-Kendr-Session: $KENDR_SESSION"

curl https://kendr.org/v1/models \
  -H "Authorization: Bearer $KENDR_API_KEY"

Build model selection from GET /v1/models at runtime. An alias can become temporarily unavailable, so avoid hardcoding assumptions about every account or environment.

Production checklist

• Create a production key with only the scopes the service requires and store it outside source control.
• Use TLS and the exact https://kendr.org base domain.
• Generate an idempotency key for every chargeable operation and preserve it across retries.
• Handle 400, 401, 402, 429, and 5xx responses deliberately; cap retry attempts.
• Set connect, read, and overall deadlines appropriate to model latency.
• Read the model catalog at runtime and provide a graceful fallback when the preferred alias is unavailable.
• Monitor latency, failures, token usage, and credits charged without logging secrets.
• Test key rotation, low-credit behavior, duplicate retries, streaming disconnects, and revoked credentials before launch.