Kendr.org

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.

API integration guide Authentication and SDKs OpenAPI JSON

Discovery Auth Credits Query execution

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, optional full_name	Sends a one-time login code through AWS SES.
POST	/api/auth/otp/verify	email, code, optional full_name	Verifies the code, creates or reuses the user, 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.

See the guide

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.

See the guide

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.

Default clients

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. Returns raw_token once plus the stored API 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.

See the guide

Use Credits and Billing for examples that fetch balance, packages, purchases, and wallet history from live customer endpoints.

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.

See the guide

Use Cloud Knowledge Bases and Hosted Vector DB for the full RAG pipeline and storage model.

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
  }
}

See the guide

Use Query examples for curl, JavaScript, and Python integration samples.

Where to go next

Quickstart

Make your first query

Use this for the end-to-end curl, JS, Python, and SDK examples against https://kendr.org.

Auth

Choose the right auth flow

Use this for cookie sessions, app sessions, API keys, OAuth PKCE, device code, and client libraries.

Wallet

Fetch credits and buy packages

Use this for dashboard balance reads, package discovery, purchases, and usage charging behavior.

Storage

Hosted vector DB

Understand how Cloud KBs store vectors, expose retrieval scores, and handle rebuilds when dimensions change.

Schema

Open the OpenAPI document

Use the live contract in Postman, generated tooling, or your own internal docs sync.