Quickstart

This quickstart takes you from a new account to a first search and a first page fetch, in four steps.

Your first search

This is the HTTP call of Run your first search, and what comes back. The agent and SDK paths ask the same question.

Request

curl -X POST https://router.telem.ai/v1/search \
  -H "Authorization: Bearer $TELEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_input": {"query": "when was the International Space Station launched"},
       "search": {"providers": {"include": ["exa", "brave"]}, "num_results": 3}}'

Response (a real one, shortened)

{
  "status": "succeeded",
  "preprocessor_runs": [
    { "preprocessor_name": "exa",
      "output_payload": { "results": [
        { "rank": 1,
          "url": "https://www.nasa.gov/history/20-years-ago-space-station-construction-begins/",
          "title": "20 Years Ago, Space Station Construction Begins - NASA" } ] } },
    { "preprocessor_name": "brave",
      "output_payload": { "results": [
        { "rank": 1,
          "url": "https://en.wikipedia.org/wiki/International_Space_Station",
          "title": "International Space Station - Wikipedia" } ] } }
  ],
  "normalized_schema_version": 2
}

Before you begin

• A Telem account. Sign in at app.telem.ai with Google or GitHub.
• For a coding agent: Node.js 20 or later (22 or later for OpenCode, Pi and OpenClaw), and the agent itself.
• For Python: Python 3.10 or later.
• For JavaScript: Node.js 20.16 or later.

Each step has a tab for a coding agent, Python, JavaScript and plain HTTP. Choose one path: the tabs keep your choice for the whole page. For any MCP client, use the MCP server. For an agent that cannot install anything, use the Agent skill.

Your first sign-in adds free credit. See Pricing for what a call costs.

Create an API key

1. Open API keys. In the console, open your project and select API keys.

2. Issue a key. Select Issue API key, name the key and tick Telem Search, then select Issue key. Telem keys start with tlm_.

3. Keep it private. Copy the key. Treat it like a password. You can show it again later in the console.

Note

Only organization admins and project Maintainers can create keys. If you do not see Issue API key, ask an admin. See API keys.

Connect Telem

Coding agent

Run the installer

Run the installer. It finds the agents on your computer. With one, it sets up that one. With more, you pick them in a menu. To see the plan first, add --dry-run: after sh -s -- on macOS and Linux, or after npx @telemai/create@latest on Windows.

macOS and Linux

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

Windows

npx @telemai/create@latest

In PowerShell, with Node.js 20 or later. Or run the macOS and Linux command in WSL or Git Bash.

The installer asks for your key. Paste a key that you already have, or choose to create a new one: the installer opens the console, and you paste the new key when you have it. A new key starts with no searches, sessions or monitors of its own. The installer checks the key and saves it in ~/.telem/credentials.json. For Claude Code, Codex, Grok Build, Muse, VS Code, Cursor and Devin Desktop it also stores the key in their own settings.

If you saved a key before and it still works, the installer uses it and does not ask. If it no longer works, the installer says so and asks for a key again. To use a different key, run the installer with --login. It checks the new key, saves it, and gives it to the agents on your computer.

macOS and Linux

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

Windows

npx @telemai/create@latest --login

In PowerShell, with Node.js 20 or later. Or run the macOS and Linux command in WSL or Git Bash.

If the key works but your account cannot pay, the installer keeps the key and tells you to add funds in the console.

The installer asks nothing about search options. It turns on auto-routing, unless ~/.telem/telem.json already sets it, and leaves the other options at Telem’s defaults. To change them, see Configuration.

To install with no prompts, for example in CI, name the agent and the variable that holds your key:

macOS and Linux

export TELEM_API_KEY=tlm_your_key
curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --yes --client claude-code --key-env TELEM_API_KEY

Windows

$env:TELEM_API_KEY = "tlm_your_key"
npx @telemai/create@latest --yes --client claude-code --key-env TELEM_API_KEY

In PowerShell, with Node.js 20 or later. Or run the macOS and Linux command in WSL or Git Bash.

Caution

--yes alone does not read TELEM_API_KEY. Without --key-env, the install finishes with no key.

With --yes, your agent keeps its built-in web search as the default. To switch the default search and fetch to Telem as well, add --claude-disable-web-search for Claude Code, --codex-disable-web-search for Codex, --grok-disable-web-search for Grok Build or --muse-disable-web-search for Muse.

For Grok Build, also add --grok-allow-telem. Without it, Grok asks before each Telem call, and a headless grok -p run cancels them.

Let your agent do it

Your agent runs the installer for you, and your key never goes into the chat. Set the key in the terminal where you start your agent, then start the agent from that terminal:

macOS and Linux

export TELEM_API_KEY=tlm_your_key

Windows

$env:TELEM_API_KEY = "tlm_your_key"

Paste this prompt into the agent:

Set up Telem web search for this coding agent.

1. Read https://docs.telem.ai/llms.txt to learn what Telem is.
2. Check that the TELEM_API_KEY environment variable is set. Do not print its
   value. If it is not set, stop and ask me to set it and restart you.
3. Run the Telem installer for this agent, with no prompts:
   curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --yes --client <client> --key-env TELEM_API_KEY
   On Windows, in PowerShell, run this instead:
   npx @telemai/create@latest --yes --client <client> --key-env TELEM_API_KEY
   For <client>, use the one that names you: claude-code, codex, grok, muse,
   vscode, cursor, devin, opencode, pi, openclaw or hermes.
4. Show me the installer's summary. Then tell me what to restart, so that
   the Telem tools load: you, or for OpenClaw, the Gateway.

DeepSeek Harness is not in the prompt: it has its own plugin, see DeepSeek Harness.

Python

export TELEM_API_KEY=tlm_your_key

pip install telem-sdk

JavaScript

export TELEM_API_KEY=tlm_your_key

npm install @telemai/sdk

HTTP

export TELEM_API_KEY=tlm_your_key

The API is at https://router.telem.ai. Send the key as Authorization: Bearer on every call.

Run your first search

Coding agent

Restart your agent so it loads Telem, then ask:

search the web for when the International Space Station was launched

The agent calls telem_search. Its answer cites the pages that Telem found.

Python

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)

The script prints the title of the first result.

JavaScript

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)

The script prints the title of the first result.

HTTP

curl -X POST https://router.telem.ai/v1/search \
  -H "Authorization: Bearer $TELEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_input": {"query": "when was the International Space Station launched"},
       "search": {"providers": {"include": ["exa", "brave"]}, "num_results": 3}}'

The response is under Your first search.

Tip

Every result has the same fields, whichever provider found it: url, title, summary, and the provider’s name on its run.

Read a page

Coding agent

read the Wikipedia page on the International Space Station and summarise its history

The agent calls telem_fetch and works from the page text.

Python

response = client.fetch(["https://en.wikipedia.org/wiki/International_Space_Station"])
page = response.results[0]
print(page.status, page.provider, len(page.content or ""))

JavaScript

const response = await telem.fetch("https://en.wikipedia.org/wiki/International_Space_Station")
const { status, provider, content } = response.results[0]
console.log(status, provider, content?.length)

HTTP

curl -X POST https://router.telem.ai/v1/fetch \
  -H "Authorization: Bearer $TELEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://en.wikipedia.org/wiki/International_Space_Station"]}'

One call takes up to 5 URLs. A URL that fails comes back as its own result with status: "failed" and the reason. The other pages still arrive.

If something goes wrong

You see	What to do
401 Missing API key	The key is not set. For an agent, run the installer again. For the SDKs or curl, export TELEM_API_KEY.
401 Invalid API key	The key was revoked or mistyped. Create a new key. Then run the installer again, pick your agents and paste the new key. Claude Code, Codex, Grok Build, Muse, VS Code, Cursor and Devin Desktop keep their own copy of the key, so they need this step.
403 API key is not authorized	The key does not have access to this call. Check the key in the console.
422 on every search	An option has a value the API does not accept. For example, autoRouting accepts only accuracy today.
The agent answers without Telem	Restart the agent, then follow its page under Integrations.
The agent says TELEM_API_KEY is not set	Export the key, then start the agent again from the same terminal.
The agent cannot run the installer	Its sandbox can block the network or changes to its own config. Run the installer yourself in a terminal, and answer its questions.

Next steps

• Auto-routing: let Telem pick the providers for each question
• Search parameters: choose providers, tiers and date windows
• API keys: where each integration looks for your key
• Errors: every error the API returns