Reference every customer-facing API route on kendr.org.
This page is the route map for the public Kendr contract. It lists the customer-facing endpoints, the accepted auth modes, the JSON body shape when a body is required, and where to find the fuller curl, JavaScript, and Python examples for each flow.
Base rules
- Base domain: https://kendr.org.
- JSON endpoints use application/json unless the route is explicitly OAuth form encoded.
- API key auth can be sent as Authorization: Bearer kndr_live_... or X-API-Key: kndr_live_....
- Customer session auth can be sent through the browser cookie, X-Kendr-Session, or an OAuth bearer token with the app scope.
- The authoritative machine-readable contracts are GET /api/openapi.json and GET /api/catalog.
Public discovery endpoints
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /api/health | No | Returns service health and database status. |
| GET | /api/catalog | No | Returns active packages, enabled surfaces, SDK resources, and public API docs metadata. |
| GET | /api/openapi.json | No | Returns the OpenAPI contract for tooling and endpoint introspection. |
Browser cookie auth endpoints
| Method | Path | Body | Response |
|---|---|---|---|
| POST | /api/auth/otp/request | email, purpose (login, signup, or backward-compatible login_or_signup) | Sends a one-time sign-in or account-verification code through AWS SES. |
| POST | /api/auth/otp/verify | email, code, purpose; signup also requires full_name and terms_accepted, with optional referral_code | Verifies the requested intent, returns user, and sets the kendr_session cookie. |
| GET | /api/auth/session | None | Returns authenticated: false or the current signed-in user. |
| POST | /api/auth/logout | None | Deletes the browser session and expires the cookie. |
Use Browser session auth for working curl examples with a cookie jar.
App auth and runtime endpoints
| Method | Path | Auth | Body or notes |
|---|---|---|---|
| POST | /api/app/auth/register | No | email, password, optional full_name. Returns a session token payload. |
| POST | /api/app/auth/login | No | email, password. Returns session.token and session.header_name. |
| GET | /api/app/auth/session | X-Kendr-Session or OAuth bearer | Returns the authenticated user plus a session descriptor. |
| POST | /api/app/auth/logout | X-Kendr-Session or OAuth bearer | Logs out the app session and revokes an OAuth access token when one is used. |
| GET | /api/app/notifications | Optional | Returns active notifications. Authenticated callers can receive authenticated-audience notices. |
| POST | /api/app/installations | Optional | Accepts installation_id, platform, app_version, channel, source, plus extra metadata. |
| POST | /api/app/activity | Optional | Accepts installation_id, platform, app_version, source, plus extra metadata. installation_id is required when no auth is present. |
| POST | /api/app/errors | Optional | Accepts message plus optional install, platform, version, error name, error code, details, stack trace, severity, and email fields. |
| POST | /api/app/feedback | Optional | Accepts message plus optional install, platform, version, category, rating, and email fields. |
Use App session auth and App telemetry endpoints for request examples.
OAuth endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /.well-known/oauth-authorization-server | Returns OAuth discovery metadata, supported scopes, grant types, and endpoint URLs. |
| GET | /oauth/authorize | Starts the PKCE authorization code flow and renders the approval screen after browser sign-in. |
| POST | /oauth/device/code | Starts the device-code flow for the CLI or another no-browser client. |
| GET or POST | /oauth/device | Human verification page for the device-code flow. |
| POST | /oauth/token | Exchanges an authorization code, device code, or refresh token for an OAuth bearer token. |
| GET | /oauth/userinfo | Returns the current OAuth user profile fields allowed by the granted scopes. |
The first-party seeded client IDs are kendr-desktop and kendr-cli. Use the auth guide for concrete PKCE and device-code examples.
Customer wallet and API key endpoints
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /api/me/dashboard | Cookie, X-Kendr-Session, or OAuth bearer | Returns the full customer dashboard payload: user, packages, api_keys, purchases, ledger, and surfaces. |
| GET | /api/me/api-keys | Cookie, X-Kendr-Session, or OAuth bearer | Returns the current customer API keys. |
| POST | /api/me/api-keys | Cookie, X-Kendr-Session, or OAuth bearer | Accepts label, optional environment, and optional least-privilege scopes. Returns raw_token once plus the stored key record. |
| POST | /api/me/api-keys/revoke | Cookie, X-Kendr-Session, or OAuth bearer | Accepts api_key_id and marks the key inactive. |
| POST | /api/me/purchases | Cookie, X-Kendr-Session, or OAuth bearer | Accepts package_id or package_slug and credits the wallet. |
| POST | /api/me/purchases/verify | Cookie, X-Kendr-Session, or OAuth bearer | Verifies the Razorpay payment signature and settles purchased credits. |
| GET | /api/me/billing/summary | API key, cookie, X-Kendr-Session, or OAuth bearer | Returns exact wallet balance, active/released reservations, settled model usage, packages, and purchases. |
| GET / POST | /api/me/ai/preferences | Cookie, X-Kendr-Session, or OAuth bearer | Reads or saves default and mode-specific Kendr model aliases for the signed-in user. |
| GET / POST | /api/me/mcp-servers | Cookie, X-Kendr-Session, or OAuth bearer | Lists, creates, or updates the user's trusted remote MCP servers. Optional bearer authorization is encrypted and never returned by the read endpoint. |
| DELETE | /api/me/mcp-servers/{server_id} | Cookie, X-Kendr-Session, or OAuth bearer | Deletes one MCP server owned by the signed-in user. |
Use Credits and Billing for examples that fetch balance, packages, purchases, and wallet history from live customer endpoints.
Governed model gateway endpoints
Model routes accept a Kendr API key with the required model scopes. The standard chargeable routes accept an optional Idempotency-Key — one is generated per request when absent, and a retry that supplies the same key replays settled usage instead of charging twice. All successful generation formats include kendr_usage.
| Method | Path | Format and purpose |
|---|---|---|
| GET | /v1/models | OpenAI model-list shape containing enabled and healthy Kendr aliases. |
| GET | /api/v1/models | Alias of /v1/models. |
| GET | /api/v1/llm/models | Desktop-compatible catalog with capabilities, availability, and credit rates. |
| POST | /v1/responses | OpenAI Responses-compatible generation; supports input, messages, instructions, tools, metadata, response format, optional Kendr optimization, web_search, and SSE. |
| POST | /v1/chat/completions | OpenAI Chat Completions-compatible generation, web_search, and SSE chunks. |
| POST | /v1/messages | Anthropic Messages-compatible request and response, including optional system, tools, web-search control, and streaming. |
| POST | /v1/messages/count_tokens | Anthropic-compatible token estimate for a message request. Free; returns input_tokens. |
| POST | /api/v1/llm/responses | Kendr Desktop legacy response shape. A request ID is generated when omitted. |
| POST | /v1/video/analyses | Queues analysis for source_url; defaults to kc-pegasus-1.2. |
| GET | /v1/video/analyses/{analysis_id} | Polls queued, running, completed, or failed video state for the owning account. |
| GET | /api/v1/openapi.json | Model-service-specific OpenAPI document. |
/api/v1/responses and /api/v1/chat/completions are supported aliases of their /v1/* forms. Prefer the shorter standard paths for new integrations.
Shared model request fields include model, input or messages, instructions, max_output_tokens, stream, web_search, tools, conversation_id, response_format, optimization, and metadata. Set web_search: false to opt out for one request, or metadata.require_web_search: true when a request must not answer without current web grounding.
For cost-saving context compression, send {"mode":"auto","engine":"auto","allow_lossy_context":true} inside optimization. See the Optimized mode API guide for curl, JavaScript, Python, streaming, billing, and receipt examples.
Tool calling is server-executed: pass {"type": "kendr_mcp", "server_id": "mcp_..."} in tools to activate a registered, trusted MCP server (at most 8 per request, OpenAI Responses routes only), and provide conversation_id so kc-intelligent keeps the selected model sticky across turns. See Call remote MCP tools for the full contract.
Cloud KB and hosted vector DB endpoints
Cloud KB routes are the public API for Kendr hosted vector storage. Callers do not upsert arbitrary vectors directly; they create, rebuild, test, and share KBs through these routes while Kendr manages extraction, chunking, embeddings, vector storage, retrieval, reranking, and evaluation history.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/kb/cloud | List hosted knowledge bases visible to the authenticated caller. |
| POST | /api/kb/cloud/estimate | Estimate chunks, source size, storage, and credits before indexing. |
| POST | /api/kb/cloud | Create a KB, store pipeline config and access policy, and queue hosted indexing. |
| POST | /api/kb/cloud/{kb_id}/test | Run retrieval and return chunks with vector, lexical, rerank, final scores, diagnostics, and answer metadata. |
| POST | /api/kb/cloud/{kb_id}/rebuild | Rebuild from extraction, cleaning, chunking, embeddings, vector storage, or retrieval config changes. |
| POST | /api/kb/cloud/{kb_id}/access | Update private, team, user, link, and source-access sharing metadata. |
| GET | /api/kb/cloud/{kb_id}/pipeline/artifacts | Inspect retained extraction, cleaning, chunking, embedding, and storage artifacts. |
| GET | /api/kb/cloud/{kb_id}/runs | Read indexing and rebuild run history with warnings, timings, and status. |
| GET | /api/kb/cloud/{kb_id}/evaluations | Read saved test queries, selected chunks, and scoring metadata. |
| DELETE | /api/kb/cloud/{kb_id} | Delete the hosted KB and its sources, chunks, artifacts, runs, evaluations, and grants. |
Use Cloud Knowledge Bases and Hosted Vector DB for the full RAG pipeline and storage model.
App connector and marketplace endpoints
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /api/me/connectors | Signed-in user | Lists Gmail, Drive, Teams, GitHub, Slack, Notion, Jira, CRM, design, and other app services available to the account with the user's connection state. |
| POST | /api/me/connectors/{connector_key}/start | Signed-in user | Returns a provider authorization URL and expiring OAuth state. |
| GET | /api/connectors/oauth/callback | Provider callback | Validates state, exchanges the authorization code, and stores the user's encrypted token set. |
| POST | /api/me/connectors/{connector_key}/disconnect | Signed-in user | Removes or revokes the user's stored authorization. |
| GET | /api/skills/catalog | Public | Lists published skill packs and install metadata. |
| GET | /api/skills/packs/{slug} | Public | Returns one published skill-pack manifest. |
| GET | /api/skills/packs/{slug}/archive | Public | Downloads the published ZIP archive. |
| GET | /api/workflows/catalog | Public | Lists workflow packs and dependency metadata. |
| GET | /api/workflows/packs/{slug} | Public | Returns one workflow-pack manifest. |
| GET / POST | /api/app/skills/installations | Signed-in user | Lists or synchronizes installed skill packs. |
| GET / POST | /api/app/workflows/installations | Signed-in user | Lists or synchronizes installed workflow packs. |
| GET / PUT | /api/app/workflows | Signed-in user | Reads or replaces the account's compiled workflow bundle. |
Developer publishing routes under /api/app/developer/skill-packs and /api/app/developer/workflow-packs support private drafts, validation, archive download, and marketplace submission. See Skills and MCP Publishing.
Unified query endpoint
POST /api/v1/query is the execution endpoint. It accepts one surface request and deducts credits only after successful execution.
| Field | Required | Meaning |
|---|---|---|
| surface | Yes | The surface key to run, such as web_search, ai_search, web_answer, google_search, google_hotels, or google_flights. |
| query | Yes | The primary query string for the selected Kendr surface. |
| params | No | An object for optional fields such as gl, hl, page, location, or travel dates. |
| Top-level optional fields | No | Optional query parameters can also sit beside surface and query. Kendr merges them with params. |
{
"surface": "google_search",
"query": "best llm observability tools",
"params": {
"gl": "us",
"hl": "en",
"page": 1
}
}
Use Query examples for curl, JavaScript, and Python integration samples.