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
`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 SDK, the OpenCode and Pi plugins, and the agent skill. The hosted MCP server (mcp.telem.ai — what the Claude Code plugin and the Codex install connect to) runs on Telem’s infrastructure, never sees these files, and runs the deployment defaults; it takes no per-key overrides today.

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`)

num_results is a call argument only, not a file key — pass it per search (client.search(..., num_results=10)).

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.

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.