Client Reference

Initialization

import { Seltz } from "seltz";

const client = new Seltz({
  apiKey: "your-api-key",       // Required (or set SELTZ_API_KEY env var)
  endpoint: "grpc.seltz.ai",    // Optional, custom gRPC endpoint
  insecure: false,              // Optional, use insecure connection
});

Configuration Options

Parameter	Type	Default	Description
`apiKey`	`string`	`undefined`	Your API key. Falls back to `SELTZ_API_KEY` env var.
`endpoint`	`string`	`grpc.seltz.ai`	gRPC endpoint (host or host:port).
`insecure`	`boolean`	`false`	Use insecure connection without TLS.

Methods

search

client.search runs a search query and returns the matching documents.

import { Seltz } from "seltz";

const client = new Seltz();

const result = await client.search({ query: "What are the best practices for TypeScript?", maxResults: 5 });

Parameters The search method accepts a single SearchParams object:

Field	Type	Required	Default	Description
`query`	`string`	Yes	-	The search query text. Keep it concise for best results.
`maxResults`	`number`	No	`10`	Maximum documents to return.
`scope`	`string`	No	-	Restrict results to a specific scope (e.g., `"news"`).
`tier`	`string`	No	`"pro"`	Which tier serves the request, `"base"` or `"pro"`. See Search tiers.
`includeDomains`	`string[]`	No	-	Include only results from these domains.
`excludeDomains`	`string[]`	No	-	Exclude results from these domains.
`fromDate`	`string`	No	-	Only include results published on or after this point. An ISO 8601 date or datetime, or an offset from now such as `now-7d`. See Filter by date.
`toDate`	`string`	No	-	Only include results published on or before this point. Same forms as `fromDate`.
`fields`	`{ content?: boolean \| ContentOptions; snippets?: boolean \| SnippetOptions }`	No	-	Which `Document` members to populate. Each takes `true`, `false`, or an object of ceilings (e.g. `{ maxCharactersPerResult: 500 }`). See Control content length and Get snippets.

Returns: Promise<SearchResponse> Filter examples:

import { Seltz } from "seltz";

const client = new Seltz();

// Filter by date
const recent = await client.search({ query: "AI news", fromDate: "2026-05-01" });

// Filter by domain
const tech = await client.search({
  query: "tech news",
  includeDomains: ["techcrunch.com", "wired.com"],
});

// Combine filters
const results = await client.search({
  query: "climate change",
  maxResults: 5,
  fromDate: "2026-01-01",
  excludeDomains: ["wikipedia.org"],
});

answer

Preview. /answer is grounded in the web scope by default, which is in beta. Pass scope to ground elsewhere — for example, news for current-events questions.

client.answer generates a direct, natural-language answer to a question, grounded in live web search results, with citations to the sources used.

import { Seltz } from "seltz";

const client = new Seltz();

const result = await client.answer({ query: "Who is going to be Apple's next CEO?" });

Parameters The answer method accepts a single AnswerParams object:

Field	Type	Required	Default	Description
`query`	`string`	Yes	-	The question to answer.
`scope`	`string`	No	-	Ground the answer in a specific scope (e.g., `"companies"`).
`includeContent`	`boolean`	No	`false`	Include the full text content of each cited source.
`model`	`string`	No	`"seltz-base"`	Answer tier. `"seltz-pro"` runs agentic RAG over a single grounding search. Requires `seltz` v2.4.0 or later.
`responseFormat`	`Record<string, unknown>`	No	-	OpenAI-style `response_format` object. The answer comes back as a JSON string matching your schema instead of Markdown. Requires `seltz` v2.5.0 or later.
`systemPrompt`	`string`	No	-	Steers how the answer is presented — tone, voice, format. Empty or whitespace-only behaves as if omitted; over 8 KiB of UTF-8 raises `SeltzAPIError`. Requires `seltz` v2.6.0 or later.

Returns: Promise<AnswerResponse> Answer tiers:

Model	Behavior
`seltz-base`	Default. One grounding search, then a direct answer.
`seltz-pro`	Agentic RAG — the model reads your request and issues the search query, then answers from the results.

An omitted or unrecognized model falls back to seltz-base; the response shape is unchanged.

import { Seltz } from "seltz";

const client = new Seltz();

const result = await client.answer({
  query: "What did Apple announce at WWDC 2026? Provide a table.",
  model: "seltz-pro",
});

Structured output: Pass responseFormat — an OpenAI-style object — to get structured output. result.answer then carries a JSON string matching your schema instead of Markdown, and inline citations no longer appear in the answer text; result.citations is returned either way. A malformed responseFormat is rejected before the request is billed, raised as SeltzAPIError.

import { Seltz } from "seltz";

const client = new Seltz();

const result = await client.answer({
  query: "Who is going to be Apple's next CEO?",
  responseFormat: {
    type: "json_schema",
    json_schema: {
      name: "leadership_change",
      schema: {
        type: "object",
        properties: {
          successor: { type: "string" },
          effective_date: { type: "string" },
        },
        required: ["successor", "effective_date"],
        additionalProperties: false,
      },
      strict: true,
    },
  },
});

const change = JSON.parse(result.answer);
console.log(change.successor, change.effective_date);
// John Ternus 2026-09-01

System prompt: Pass systemPrompt to steer how the answer is presented — tone, voice, format.

import { Seltz } from "seltz";

const client = new Seltz();

const result = await client.answer({
  query: "Who is going to be Apple's next CEO?",
  systemPrompt:
    "Write as an analyst briefing an executive. Open with a one-line bottom line, then at most three supporting bullets. Avoid hedging language.",
});

Example:

import { Seltz } from "seltz";

const client = new Seltz();

const result = await client.answer({ query: "Who is going to be Apple's next CEO?", includeContent: true });

console.log(result.answer);

for (const citation of result.citations) {
  console.log(`Source: ${citation.url}`);
  console.log(`Content: ${citation.content}`);
  console.log("---");
}

answerStream

client.answerStream streams an answer as the model generates it, instead of waiting for the whole thing. It accepts an AnswerStreamParams object with the same fields as answer. Requires seltz v2.3.0 or later. The stream yields AnswerStreamResponse events, and each event holds exactly one member in event.event. Switch on event.event.case: the first event is "citations", the next events are "textDelta" chunks of the answer, and the final event is "finishReason".

import { Seltz } from "seltz";

const client = new Seltz();

for await (const event of client.answerStream({ query: "Who is going to be Apple's next CEO?" })) {
  switch (event.event.case) {
    case "citations":
      console.log(event.event.value.citations.map((citation) => citation.url));
      break;
    case "textDelta":
      process.stdout.write(event.event.value);
      break;
  }
}

Returns: AsyncIterable<AnswerStreamResponse>

Calling answerStream doesn’t send the request. The request goes out when you start iterating, so errors are thrown inside the for await loop, not at the call. Wrap the whole loop in your try:

import { Seltz, SeltzError } from "seltz";

const client = new Seltz();

try {
  for await (const event of client.answerStream({ query: "Who is going to be Apple's next CEO?" })) {
    if (event.event.case === "textDelta") {
      process.stdout.write(event.event.value);
    }
  }
} catch (error) {
  if (error instanceof SeltzError) {
    console.error(`Stream failed: ${error.message}`);
  }
}

A stream also has no per-call deadline. answer gives up after 30 seconds, but answerStream keeps going until the answer finishes.

fetch

client.fetch retrieves the content of up to 20 URLs you already have and returns each page as Markdown. Requires seltz v2.9.0 or later.

import { FetchStatus, Seltz } from "seltz";

const client = new Seltz();

const response = await client.fetch({ urls: ["https://example.com/"] });

for (const result of response.results) {
  if (result.status === FetchStatus.OK) {
    console.log(result.markdown);
  }
}

A URL that fails doesn’t throw. It comes back as a result with status set to FetchStatus.ERROR and an error.code, so check each result before you read it. Returns: Promise<FetchResponse>, with one FetchResult per requested URL. The fetch method accepts a single FetchParams object. See the Fetch reference for its fields (urls, formats, tier, timeoutMs), the result fields, and the per-URL error codes.

agent

client.agent runs multi-step research over the web and returns a cited report. Requires seltz v2.9.0 or later. Runs are asynchronous. create returns the run in pending state, and createAndWait starts a run and resolves once it reaches a terminal state.

import { Seltz } from "seltz";

const client = new Seltz();

const run = await client.agent.createAndWait({
  query: "What are the three most notable AI-company acquisitions announced in 2026?",
});

console.log(run.output?.text);
for (const source of run.output?.sources ?? []) {
  console.log(`[${source.id}] ${source.url}`);
}

The namespace’s methods are create, get, list, cancel, wait, and createAndWait. See SDK methods for what each returns. Check run.status and run.stopReason before you rely on the output: a run can end failed. See the Agent reference for the request fields, the run envelope, and what each status and stop reason means.

monitor

client.monitor manages monitors, which run a set of saved searches on a schedule and deliver each new document once. Requires seltz v2.7.0 or later.

import { Seltz } from "seltz";

const client = new Seltz();

const response = await client.monitor.create({
  name: "my-first-monitor",
  cadence: "1h",
  searchRequests: ["best ai search engines", "ai search funding"],
});

const monitorId = response.monitor!.monitorId;

const page = await client.monitor.listRecords(monitorId, { limit: 100 });

for (const record of page.records) {
  if (record.payload.case !== "searchResult") continue;
  console.log(record.recordId, record.payload.value.document?.url);
}

The namespace’s methods are create, get, list, update, delete, listRuns, getRun, listRunRequests, listRecords, listRunRecords, and streamRecords. Each returns the whole response message, so read response.monitor rather than expecting the monitor itself. See SDK methods for what each returns, the rest of the Monitor reference for paging, cadence, limits, and errors, and Webhooks to be told when a run finishes.

Response Types

SearchResponse

interface SearchResponse {
  documents: Document[];
}

interface Document {
  url?: string;            // URL of the source document
  content?: string;        // Document content/snippet
  publishedDate?: string;  // Publication date (ISO 8601)
}

Example:

import { Seltz } from "seltz";

const client = new Seltz();

const result = await client.search({ query: "TypeScript generics", maxResults: 10 });

console.log(`Found ${result.documents.length} documents`);

for (const doc of result.documents) {
  console.log(`URL: ${doc.url}`);
  console.log(`Content: ${doc.content}`);
  console.log("---");
}

AnswerResponse

interface AnswerResponse {
  answer: string;          // Markdown-formatted answer text
  citations: Citation[];   // Sources used to ground the answer
}

interface Citation {
  url: string;       // URL of the cited source
  content?: string;  // Source content (present only when includeContent is true)
}

Example:

import { Seltz } from "seltz";

const client = new Seltz();

const result = await client.answer({ query: "What's the latest on Apple's CEO succession?" });

console.log(result.answer);

for (const citation of result.citations) {
  console.log(citation.url);      // URL of the cited source
  console.log(citation.content);  // Source content (undefined unless includeContent is true)
}

AnswerStreamResponse

One event from answerStream. Each event sets exactly one member of event.

interface AnswerStreamResponse {
  event:
    | { case: "citations"; value: Citations }  // First event: the sources, in value.citations
    | { case: "textDelta"; value: string }     // Middle events: the next chunk of answer text
    | { case: "finishReason"; value: string }  // Final event: why the answer stopped
    | { case: undefined; value?: undefined };
}

Error Types

All errors extend SeltzError.

Error	Description
`SeltzConfigurationError`	Missing or invalid configuration (e.g., no API key).
`SeltzAuthenticationError`	Invalid or expired API key.
`SeltzConnectionError`	Cannot connect to the service.
`SeltzTimeoutError`	Request timed out (default: 30 seconds).
`SeltzRateLimitError`	Too many requests. Wait before retrying.
`SeltzAPIError`	General API error. Check `code` and `details` properties.

This example constructs the client outside the try, so a missing SELTZ_API_KEY throws SeltzConfigurationError at startup rather than per query. The handler covers only the errors search() can throw.

import {
  Seltz,
  SeltzError,
  SeltzAuthenticationError,
  SeltzAPIError
} from "seltz";

const client = new Seltz();

try {
  const result = await client.search({ query: "..." });
} catch (error) {
  if (error instanceof SeltzAuthenticationError) {
    console.error('Check your API key');
  } else if (error instanceof SeltzAPIError) {
    console.error(`Error: ${error.message}`);
    console.error(`Code: ${error.code}`);
    console.error(`Details: ${error.details}`);
  } else if (error instanceof SeltzError) {
    console.error(`SDK error: ${error.message}`);
  }
}

TypeScript Types

Import types directly from the package. These are the ones you use most:

import type {
  Seltz,
  SeltzOptions,
  // Search and Answer
  SearchParams,
  SearchResponse,
  Document,
  AnswerParams,
  AnswerResponse,
  AnswerStreamParams,
  AnswerStreamResponse,
  Citation,
  Citations,
  // Fetch
  FetchParams,
  FetchResponse,
  FetchResult,
  FetchError,
  // Agent
  CreateAgentRunParams,
  AgentRun,
  AgentRunOutput,
  AgentRunSource,
  // Monitor
  CreateMonitorParams,
  UpdateMonitorParams,
  Monitor,
  Run,
  Record,
  Webhook,
  SeltzError,
} from "seltz";

The status enums are values, not just types, so import them without type when you compare against them:

import {
  FetchStatus,
  AgentRunStatus,
  AgentRunStopReason,
  MonitorStatus,
  RunStatus,
} from "seltz";

Getting Started

Web Tools

Data

Tutorials

Chat

Integrations

SDKs

Client Reference

Initialization

Configuration Options

Methods

search

answer

answerStream

fetch

agent

monitor

Response Types

SearchResponse

AnswerResponse

AnswerStreamResponse

Error Types

TypeScript Types

​Initialization

​Configuration Options

​Methods

​search

​answer

​answerStream

​fetch

​agent

​monitor

​Response Types

​SearchResponse

​AnswerResponse

​AnswerStreamResponse

​Error Types

​TypeScript Types

Initialization

Configuration Options

Methods

search

answer

answerStream

fetch

agent

monitor

Response Types

SearchResponse

AnswerResponse

AnswerStreamResponse

Error Types

TypeScript Types