Parameters & Configuration

The API reference is the exhaustive wire contract, generated from the server’s own schema — every endpoint, every field, every status code. This page is the curated half: the parameters worth setting, what each one does and costs, and — in the last section — how the plugins and the SDK persist them. Each operation’s options are listed below with a line each; what they DO is a page apiece, Search parameters and Fetch parameters.

Connecting

TELEM_API_KEY is your credential; TELEM_BASE_URL points a client at a non-hosted deployment and defaults to https://router.telem.ai. Both are environment variables. The guided installer writes your key to ~/.telem/credentials.json, so you usually set neither by hand. Full rules on Authentication.

Search

Everything tunable about a search rides in the request’s search block:

{
  "user_input": { "query": "istio vs linkerd" },
  "search": {
    "tier": "extended",
    "providers": { "include": ["exa", "brave"] },
    "num_results": 5
  }
}

Parameter	What it does
`auto_routing`	Let Telem pick the providers for each query from its topic. See Auto-routing.
`tier`	How much detail each result carries. See Tier.
`fields`	Name the result fields you want instead of a tier. Mutually exclusive with `tier`.
`providers.include`	Replace the deployment’s provider set. See Providers.
`providers.exclude`	Drop providers from the set that would otherwise run.
`num_results`	Results per provider, `1`–`20`. See Results per provider.
`include_full_content`	Ask providers for whole page content. See Full page content.
`provider_overrides`	Pass provider-native parameters through, keyed by provider. See Provider overrides.
`include_raw`	Return each provider’s original payload alongside the normalized results. See Raw provider payloads.

Search parameters → — what each option does, what it costs, and the raw field behind every normalized one, provider by provider.

Fetch

POST /v1/fetch reads whole web pages by URL — several per call, fetched as one batch. Everything tunable about a fetch rides in the request’s options block:

{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "options": { "tier": "extended", "content_format": "markdown" }
}

Option	Type	Default	What it does
`tier`	`minimalist` \| `default` \| `extended` \| `max`	`"default"`	How much each page carries. See Tier.
`content_format`	`"markdown"` \| `"text"`	`"markdown"`	Format of the page body. See Page content.
`inline_content`	`bool`	`true`	`false` returns the metadata without the page text. See Page content.
`inline_max_chars`	`int`	20 000	Per-page cap; longer pages are truncated and flagged. See Page content.
`providers`	`array<string>`	the deployment’s chain, in order	Pin the chain to specific providers. See Providers.

Fetch parameters → — the tier ladder, the provider chain, and the raw field behind every normalized one, provider by provider.

Request limits

Per-request shape caps, checked before the request is billed — a rejected request leaves nothing behind.

Limit	Value	Applies to
URLs per fetch	set per deployment	one `POST /v1/fetch` call — over the cap is a `400` naming the limit
Results per provider	1–20	`num_results`
Queries per batch	32	a list of queries
Volume budget	160	queries × results, on every search

Non-fatal events — a provider clamped your count, a provider that structurally cannot supply a requested field — come back as {code, message} entries in each run’s warnings, never as errors.

Configuring the plugins and the SDK

The plugins and the SDK send the same request — a config file or environment variable just fixes a parameter’s value so every search they make carries it.

This section covers the surfaces that run on your machine: the Python and JavaScript SDKs, the OpenCode, Pi and DeepSeek Harness plugins, and the agent skill.

The Claude Code plugin and the Codex install reach Telem through the hosted MCP server (mcp.telem.ai), which runs on Telem’s infrastructure and reads no files of yours. The options below still apply to them: each plugin resolves your config and sends it with every search it makes. The copy-paste setup for other MCP clients has no plugin alongside it, so it runs the deployment’s own defaults.

Options go in .telem/telem.json — one per project, one per user:

{
  "tier": "extended",
  "providersInclude": ["exa", "brave"]
}

Request parameter	File key	Environment
`search.tier`	`tier`	`TELEM_TIER`
`search.fields`	`fields`	`TELEM_FIELDS` (comma-separated)
`search.providers.include`	`providersInclude`	`TELEM_PROVIDERS_INCLUDE` (comma-separated)
`search.providers.exclude`	`providersExclude`	`TELEM_PROVIDERS_EXCLUDE` (comma-separated)
`search.include_full_content`	`fullContent`	`TELEM_FULL_CONTENT` (only the exact string `1`)
`search.auto_routing`	`autoRouting`	`TELEM_AUTO_ROUTING`

num_results is a call argument only, not a file key — pass it per search (client.search(..., num_results=10), or telem.search(..., { numResults: 10 }) in JavaScript).

The JavaScript SDK reads the TELEM_* variables and the credentials file only. It never opens .telem/telem.json. Set its search defaults as constructor options (new Telem({ tier: "extended" })) or call arguments. The environment applies below them.

Precedence

Project file, then user file, then TELEM_* — resolved per key, so a project file that sets only tier leaves the rest to the levels below it, and per call, so an edit takes effect on the next search with no restart. OpenClaw is the exception: it has no .telem/telem.json layer, and its options (and its credentials) live in its own plugin config with TELEM_* beneath.

The DeepSeek Harness plugin adds one level above the files rather than replacing them: its row in your profile patch, then the project file, then the user file, then TELEM_*. The project is the calling agent’s session directory. It is also the one surface with no deprecated host-specific file in the ladder — there was never one to keep reading.

The installer sets autoRouting for you: npm create @telemai asks about it as a step of its own — whatever you answer to “Customize search defaults?” — and writes accuracy unless you answer no, which writes off. Pass --auto-routing accuracy or --auto-routing off to answer without the question. accuracy is available now; latency and search_cost routing are coming shortly — the key already accepts all three, and the installer offers each one as it becomes available.

autoRouting is the one exception to that order: TELEM_AUTO_ROUTING beats both files, so an operator can change the mode for one shell without editing a file. A mode (accuracy today) lets the server choose which providers run each search and what to optimise for; off, or no key at all, means the configured provider set runs unchanged. What auto-routing does is on Auto-routing.

tier and fields are mutually exclusive; when both are set the more specific level wins. When both provider halves resolve, providersExclude is subtracted from providersInclude before the request goes out.

Incremental transmission

The OpenCode, OpenClaw and Pi plugins and the Python SDK’s OpenAI and Hermes integrations send conversation lineage incrementally by default: a subagent’s inherited context travels once, not on every search. Nothing to configure — the client verifies the backend supports it before ever omitting anything, so older or self-hosted backends simply keep receiving the full payload. TELEM_INCREMENTAL=off (environment only, no file key) restores full transmission on every call; it exists as an operational rollback lever, not a tuning knob. The JavaScript SDK’s Vercel AI SDK integration sends incrementally in the same way. Lineage data you build by hand with buildMetadata is sent in full on every call.

The DeepSeek Harness plugin does not do this yet: every search it makes carries the full lineage payload, including a subagent’s inherited context. Correctness is unaffected — it is bytes on the wire, not missing data.

Update notice

The OpenCode, OpenClaw and Pi plugins and the Python SDK’s OpenAI and Hermes integrations show a one-time notice when a newer plugin or SDK version is available, naming the exact command to update. It is notify-only — it never updates or installs anything on its own — and it stays quiet by default in non-interactive and CI runs. Set TELEM_NO_UPDATE_NOTICE=1 (environment only, no file key) to silence the “a newer version is available” notice. The JavaScript SDK shows no notice, and neither does the DeepSeek Harness plugin — update it with dsh plugin --profile <name> add @telemai/dsh-plugin when you choose to.