Make your first Kendr API request in under five minutes.

Quickstart: one key, one request

What you need: a funded Kendr account and a scoped API key created in API keys. Save the key when it is created; its full value is shown once. Keep it on your server or in a local environment variable, never in browser code.

1. 1
   Set your key

   export KENDR_API_KEY="kndr_live_..." on macOS/Linux, or $env:KENDR_API_KEY="kndr_live_..." in PowerShell.
2. 2
   Send a chat completion

   Use kendr-intelligent for request-by-request routing, or replace it with an available alias returned by GET /v1/models.
3. 3
   Keep the receipt

   Read the standard response fields plus kendr_usage and, for routed requests, kendr_routing.

curl https://api.kendr.org/v1/chat/completions \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kendr-intelligent",
    "messages": [{"role": "user", "content": "Reply with exactly five words."}]
  }'

A successful response uses the OpenAI Chat Completions shape and adds Kendr settlement metadata. For production retries, also send a stable Idempotency-Key; the server generates a request identifier when you omit one.

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://api.kendr.org and pasting one scoped key. Use model: "kendr-intelligent" for general managed routing with optimized context, kendr-intelligent-direct for general routing with original context, kendr-coder for coding-focused routing with optimized context, or kendr-coder-direct for coding-focused routing with original context. You can also use an exact or account-owned alias returned by GET /v1/models. Unknown aliases fail closed so typos cannot silently change routing or billing. Paste the key you saved at creation in place of <YOUR_KEY> below — full keys are never shown again.

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

from openai import OpenAI

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

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

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

import anthropic

client = anthropic.Anthropic(base_url="https://api.kendr.org", auth_token="<YOUR_KEY>")
msg = client.messages.create(
    model="kendr-intelligent", 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://api.kendr.org/v1",
      "api": "openai-completions",
      "apiKey": "$KENDR_KEY",
      "models": [{ "id": "kendr-intelligent", "name": "Kendr Intelligent" }]
    }
  }
}

// shell
export KENDR_KEY=<YOUR_KEY>

Know the pricing and credit policy

All model aliases and routing modes use one fixed 5% markup on the configured provider cost. Exact aliases and Kendr managed routing do not have different markup percentages. Credits added by a completed paid package purchase never expire; promotional grants can have a grant-specific expiration.

• Use the public catalog's pricing_policy and per-model pricing fields for public quotes.
• Use authenticated GET /v1/models for models and rates available to the current account.
• Use kendr_usage.credits_charged_micros as the authoritative settled model charge.
• Use the wallet activity or billing summary to distinguish non-expiring purchased lots from expiring promotional lots.

See Credits and billing for package and lot behavior.

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.

Discover public models without a key

curl https://api.kendr.org/api/public/models

{
  "object": "list",
  "version": "sha256:<content-digest>",
  "last_updated": "<RFC3339 timestamp>",
  "pricing_policy": {
    "currency": "credits",
    "markup_percent": 5,
    "normal_markup_percent": 5,
    "intelligent_markup_percent": 5,
    "quote_basis": "default_available_route"
  },
  "data": [
    {
      "id": "<public alias>",
      "slug": "<public alias>",
      "display_name": "<display name>",
      "family": "<model family>",
      "mode": "normal",
      "context_window": 0,
      "latency_tier": "<tier>",
      "capabilities": [],
      "available": true,
      "availability": "available",
      "status_reason": "Available for API requests.",
      "pricing": {
        "currency": "credits",
        "credits_per_million_input": 0,
        "credits_per_million_cached_input": 0,
        "credits_per_million_output": 0,
        "tiers": []
      }
    }
  ]
}

The values above illustrate the response shape, not a quoted model or price. Read the live payload, retain its version with generated pages or cached records, and refresh when that content digest changes. Use GET /v1/models after authentication because account-specific availability can differ.

curl https://api.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": "kendr-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.

Choose a Kendr Route through the API

Kendr Routes bundle model selection and context behavior into the model alias. Choose an optimized alias when Kendr Optimizer should prepare eligible context before the provider call, or choose the matching Direct alias when the provider must receive the original context. Do not add a client-selected optimization policy to a managed-route request.

Optimized coding request

curl https://api.kendr.org/v1/responses \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Idempotency-Key: coder-request-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kendr-coder",
    "input": "Review the implementation and propose a safe patch."
  }'

JavaScript: general routing with original context

const response = await fetch("https://api.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: "kendr-intelligent-direct",
    input: "Summarize the relevant decisions in this project context."
  })
});

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);

Python: coding routing with original context

import os
import uuid
import requests

response = requests.post(
    "https://api.kendr.org/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['KENDR_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "kendr-coder-direct",
        "input": "Review the implementation and propose a safe patch.",
    },
    timeout=180,
)
response.raise_for_status()
result = response.json()
print(result["output_text"])

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": "kendr_optimizer",
    "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.

Optimized managed routes can return kendr_optimization with the server-selected engine, estimated input reduction, quality checks, and fallback state. Direct routes preserve original context and must not be presented as optimized.

Streaming

Set stream: true on the same alias-based request. The final done event contains settled usage and, for optimized routes, 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. Safe routes relay provider deltas live. Tool combinations that cannot preserve a provider-owned trace safely return one complete JSON response on the Kendr-native endpoint, with X-Kendr-Stream-Mode: buffered and X-Kendr-Buffered-Reason; compatibility endpoints retain their vendor SSE wire format.

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://api.kendr.org/v1/responses \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Idempotency-Key: web-search-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kendr-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

OAuth app connectors and custom MCP servers are different integrations. App connections are discovered from the authenticated account with {"type": "kendr_app", "selection": "auto"}; Kendr managed routing retains only apps relevant to the current request before it chooses a tool-capable route. The MCP contract below is for a specific custom server chosen by ID.

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://api.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://api.kendr.org/v1/responses \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Idempotency-Key: mcp-demo-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kendr-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 kendr-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.
• Kendr-attested read-only OAuth app tools can stream assistant text while credentials and tool progress remain private. Custom kendr_mcp servers and stateful multi-stage tool combinations return one complete response because their hidden provider trace or side effects cannot safely be replayed after a disconnect.
• 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, Kendr managed routing 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://api.kendr.org/v1"
});

const response = await client.responses.create({
  model: "kendr-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://api.kendr.org/v1",
)

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

print(response.output_text)

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

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

Migrate an OpenAI client

You do not need to replace the OpenAI Python or JavaScript package. Change the API key, base URL, and model alias; keep the rest of a supported Chat Completions or Responses call intact. Test the exact request fields you use before moving production traffic because Kendr does not claim compatibility with every OpenAI endpoint or every provider-specific extension.

from openai import OpenAI
import os

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

result = client.chat.completions.create(
    model="kendr-intelligent",
    messages=[{"role": "user", "content": "Summarize this design."}],
)
print(result.choices[0].message.content)

Supported compatibility routes are GET /v1/models, POST /v1/chat/completions, and POST /v1/responses. Anthropic-format clients can use POST /v1/messages and POST /v1/messages/count_tokens. File uploads, assistants, fine-tuning, realtime sessions, and other unrelated vendor APIs are not implied by “compatible.”

Use Kendr with the Vercel AI SDK

The Vercel AI SDK has an OpenAI-compatible provider adapter. Configure it on your server with the Kendr /v1 base URL and a Kendr key. Do not expose the key through a client component or public environment variable.

npm install ai @ai-sdk/openai-compatible

import { generateText } from "ai";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

const kendr = createOpenAICompatible({
  name: "kendr",
  apiKey: process.env.KENDR_API_KEY,
  baseURL: "https://api.kendr.org/v1",
  includeUsage: true,
});

const { text, usage } = await generateText({
  model: kendr.chatModel("kendr-intelligent"),
  prompt: "Give me a three-step rollout plan.",
});

console.log(text, usage);

Request structured JSON

Send response_format when the selected model route advertises structured_output in GET /v1/models. Kendr managed routing filters its candidates for that capability. An exact alias without the capability fails instead of silently dropping the schema.

curl https://api.kendr.org/v1/chat/completions \
  -H "Authorization: Bearer $KENDR_API_KEY" \
  -H "Idempotency-Key: structured-ticket-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kendr-intelligent",
    "messages": [{"role": "user", "content": "Classify: Checkout fails after payment."}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "category": {"type": "string"},
            "urgent": {"type": "boolean"}
          },
          "required": ["category", "urgent"],
          "additionalProperties": false
        }
      }
    }
  }'

Treat the returned assistant content as untrusted input until your application parses and validates it against the same schema. Compatibility support routes the request to a capable model; it does not replace application-side validation.

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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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"])
}

Source-included helper clients

This repository includes dependency-light helper clients for JavaScript and Python. Use these from the checked-out source or your internal package registry when you want a thinner call surface around the raw HTTP routes, or call the HTTPS endpoints directly from any other runtime. A package manifest is not evidence of a public npm or PyPI release; verify a registry release independently before using an install command.

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

const client = new KendrClient({
  apiKey: process.env.KENDR_API_KEY,
  baseUrl: 'https://api.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://api.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://api.kendr.org/api/catalog

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

curl https://api.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": "kendr-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": {
    "receipt_id": "kr_86f82eb4d7a54fa2b30d8ce43e7d5f72",
    "request_id": "0887c41b-5285-409d-ad04-b900b9a258c3",
    "policy_version": "balanced-v1",
    "catalog_version": "catalog-2026-08-12",
    "pricing_version": "cloud-v1",
    "rate_card_version": "2026-08-12T00:00:00Z",
    "requested_model": "kendr-intelligent",
    "selected_model_alias": "kc-llama-4-scout",
    "task_category": "flash",
    "reason_code": "trivial_greeting_cheapest_fast",
    "confidence": "0.95",
    "tools": [],
    "latency_ms": 842,
    "attempted_candidates": [
      {"attempt": 1, "selected_model_alias": "kc-llama-4-scout", "status": "succeeded", "latency_ms": 842}
    ],
    "usage": {
      "input_tokens": 36,
      "cached_input_tokens": 0,
      "cache_write_tokens": 0,
      "output_tokens": 25,
      "reasoning_tokens": 0,
      "total_tokens": 61
    },
    "cost": {
      "currency": "credits",
      "credits_charged_micros": 11650,
      "credits_charged": "0.01165"
    }
  },
  "kendr_optimization": {
    "enabled": true,
    "requested_mode": "balanced",
    "resolved_mode": "balanced",
    "engine": "kendr_optimizer",
    "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://api.kendr.org/v1
KENDR_MODEL=kendr-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, call the empty-body POST /api/v1/llm/responses/replay with the original idempotency key. That lookup can never start another generation.
• 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://api.kendr.org/api/me/billing/summary \
  -H "X-Kendr-Session: $KENDR_SESSION"

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

Build authenticated model selection from GET /v1/models at runtime. Use unauthenticated GET /api/public/models for public directories or pre-login discovery; its versioned response exposes public capabilities, availability, and credit rates but deliberately omits private provider routes and account-specific aliases. 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://api.kendr.org API 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.