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, provider metadata, 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/register	email, password, optional full_name	Creates the user, returns user, and sets the kendr_session cookie.
POST	/api/auth/login	email, password	Authenticates the user, returns user, and refreshes the browser 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.

Unified query endpoint

POST /api/v1/query is the execution endpoint. It accepts one surface request, routes it through the live provider configuration, and deducts credits only after a successful provider response.

Field	Required	Meaning
surface	Yes	The surface key to run, such as google_search, google_images, google_hotels, or google_flights.
query	Yes	The primary query string. Kendr also maps it into q for upstream providers when needed.
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.

Schema

Open the OpenAPI document

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