Quickstart

Three ways in. All three need a key, so start there.

First: get a key

Create one under API keys in the Telem console; keys are project-scoped — see Authentication. The hosted router at https://router.telem.ai requires one, and without it a request returns 401 {"detail": "Missing API key"}.

Path 1 — install into the agents you already run

The only path with retrieval metrics and trajectory analytics.

curl -fsSL https://docs.telem.ai/install.sh | sh

1. It detects your frameworks. Claude Code, Codex, OpenCode, OpenClaw, Pi — undetected ones stay in the list with a note, not hidden.

2. You pick. Space toggles, Enter confirms — everything you select installs in one run.

3. It validates your key against the router before writing anything, re-prompting a rejected one.

4. It writes. Each plugin through its host’s own install path, and your key to ~/.telem/credentials.json (mode 0600).

Useful flags — pass them after sh -s --:

Flag	What it does
--dry-run	Print the plan and change nothing
--client codex	Skip the menu; repeat for several. Ids: claude-code, codex, opencode, openclaw, pi, mcp-json
--yes	No prompts (reads TELEM_API_KEY) — the CI path

curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --dry-run

Then restart the apps it installed into and ask your agent to search. Per-framework detail: Claude Code · Codex · MCP server · OpenCode · OpenClaw · Pi · Hermes

Path 2 — teach an agent the API, install nothing

No plugin, no console, no change to your host.

npx skills add https://docs.telem.ai

One page teaches your coding agent to call the API directly — see Agent skill. Or call it yourself:

curl

# The hosted router at https://router.telem.ai REQUIRES a key: an unauthenticated
# request gets 401 {"detail": "Missing API key"}. The header is still built
# conditionally because a SELF-HOSTED deployment can be configured to run open,
# and an empty "Bearer " header would make such a deployment reject an otherwise
# valid request.
auth_header=()
if [ -n "${TELEM_API_KEY:-}" ]; then
  auth_header=(-H "Authorization: Bearer $TELEM_API_KEY")
fi

curl -s -X POST "$TELEM_BASE_URL/v1/search" \
  "${auth_header[@]}" \
  -H "Content-Type: application/json" \
  -d '{"user_input": {"query": "when was the International Space Station launched"},
       "search": {"providers": {"include": ["exa", "brave"]}, "num_results": 5}}'

Set up the environment

export TELEM_API_KEY=...                        # your key
export TELEM_BASE_URL=https://router.telem.ai   # curl needs this spelled out

The SDK and the plugins default TELEM_BASE_URL to https://router.telem.ai; curl does not, and the snippet interpolates the variable, so unset it fails with curl: (3) URL rejected.

The example pins search.providers.include to ["exa", "brave"] — embedding-based plus independent keyword index, covering both retrieval styles. Widen the list when recall matters more than the bill.

Full API reference →

Path 3 — call it from Python

1. Install the SDK.

   pip install telem-sdk

2. Make a search call. The client reads TELEM_API_KEY and TELEM_BASE_URL from the environment, falling back to ~/.telem/credentials.json if the npm wizard wrote one.

   from telem import Telem
   
   client = Telem()  # reads TELEM_API_KEY / TELEM_BASE_URL from env
   response = client.search("when was the International Space Station launched")
   print(response.results[0].title)

3. Check the output. The sample prints the top result’s title, some International Space Station headline. Ranking varies, so don’t match an exact string.

For JavaScript, install the same client for Node and TypeScript:

npm install @telemai/sdk

import Telem from "@telemai/sdk"

const telem = new Telem() // reads TELEM_API_KEY / TELEM_BASE_URL from env
const response = await telem.search("when was the International Space Station launched")
console.log(response.results[0].title)

See the JavaScript SDK page for the rest.

Per-search options (tier, fields, provider include/exclude, num_results, full content) are call arguments here — see the Python SDK page or the JavaScript SDK page and the config reference.

Which path was that?

	Path 1 — installer	Path 2 — skill / REST	Path 3 — Python / JavaScript SDK
Agent gets search and page fetch as tools	yes	you wire it	you wire it
Retrieval metrics + trajectory analytics	yes	no	no
Touches your framework config	yes	no	no
Needs a Telem key	yes	yes	yes
Time	seconds	one command	one command