API reference

Everything the observra-sdk-node package exports.

import * as observra from "observra-sdk-node";

The package is ESM-only and exposes exactly one entry point. Deep imports (observra-sdk-node/dist/...) are blocked — internals are free to change between versions.

Functions

configure(options?)

Sets up the SDK. Call once at startup, before constructing provider clients.

function configure(options?: ConfigureOptions): ObservraConfig;

ConfigureOptions

Option	Type	Default	Notes
gatewayKey	string	OBSERVRA_GATEWAY_KEY	Required. Starts with obs_
serviceName	string	"observra-app"	Names your service in trace data
guardrailMode	"warn" | "redact" | "block"	"warn"	See Guardrails
gatewayUrl	string	OBSERVRA_GATEWAY_URL, else https://gateway.observra.in	Self-hosted gateways only
insecure	boolean	false	Permits a plaintext http:// gateway URL. Local development only
promptInjectionDetection	boolean	OBSERVRA_PROMPT_INJECTION_DETECTION, else unset	0.2.0. Unset, true and false are three distinct states — see Configuration

Returns ObservraConfig

interface ObservraConfig {
  gatewayUrl: string;
  gatewayKey: string;
  serviceName?: string;
  tracer: Tracer;          // OpenTelemetry Tracer
  guardrailMode: GuardrailMode;
  promptInjectionDetection?: boolean;   // undefined means "send no header"
}

tracer is the useful one — see Tracing.

Throws if gatewayKey resolves to nothing, or if the gateway URL is plaintext http://.

instrument()

function instrument(): Promise<void>;

Patches the global fetch so provider SDKs and agent frameworks route through your gateway and carry trace context. Detects and patches supported agent frameworks.

Async, idempotent, and must be awaited. Only needed for keeping your own SDK.

shutdown()

function shutdown(): Promise<void>;

Flushes buffered spans and closes the SDK's connections to the gateway. Idempotent, safe before configure(), and never throws.

Usually unnecessary — a natural exit flushes via beforeExit. Reach for it in a short-lived script that would otherwise exit with spans still queued. One-way: after it resolves, nothing further is exported. See Configuration, including the process.exit() caveat on Windows.

Provider clients

All take { apiKey: string }.

OpenAI-protocol clients

new observra.Groq({ apiKey }).chat.completions.create(params)

OpenAI · Groq · Cerebras · Azure · Ollama · OpenRouter · TokenRouter · Together · Fireworks · DeepSeek · XAI · Mistral · NIM · LMStudio · Cohere · HuggingFace

interface ChatCompletionParams {
  model: string;
  messages: Array<{ role: string; content: unknown }>;
  stream?: boolean;
  [key: string]: unknown;   // any other provider parameter passes through
}

create() returns Promise<unknown> — or Promise<AsyncIterable<unknown>> when stream: true, via an overload, so for await type-checks.

Anthropic

new observra.Anthropic({ apiKey }).messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 256,
  messages: [{ role: "user", content: "Hello" }],
});

Gemini

new observra.Gemini({ apiKey }).models.generateContent({
  model: "gemini-2.0-flash",
  contents: "Hello",
});

Vertex, Bedrock

Exported but not usable yet — both need extra per-request headers the transport can't pass. See Providers.

Errors

GatewayError

Thrown by SDK provider clients when the gateway or provider returns a non-2xx response.

class GatewayError extends Error {
  readonly status: number;   // HTTP status
  readonly body: unknown;    // parsed response body
}

try {
  await client.chat.completions.create({ /* ... */ });
} catch (err) {
  if (err instanceof observra.GatewayError) {
    console.error(err.status, err.message);
    if (err.status === 401) console.error("check your gateway key");
    if (err.status === 429) console.error("rate limited");
  }
}

The message is extracted from whichever error shape the provider used, so you get the provider's actual text rather than a generic failure.

:::note Native SDKs throw their own errors On keeping your own SDK, errors come from your provider's SDK, not from GatewayError — the SDK only reroutes the request. A bad gateway key surfaces as whatever that SDK raises on a 401. :::

GuardrailViolation

Thrown when guardrailMode: "block" and content matched a pattern. The request is never sent.

class GuardrailViolation extends Error {
  readonly violations: Array<{ label: string; /* ... */ }>;
}

catch (err) {
  if (err instanceof observra.GuardrailViolation) {
    console.error(err.violations.map((v) => v.label));  // ["ssn", "email"]
  }
}

Labels are listed in Guardrails.

Full export list

Export	Kind
configure	function
instrument	function
shutdown	function
GatewayError	error class
GuardrailViolation	error class
OpenAI Groq Cerebras Azure Ollama OpenRouter TokenRouter Together Fireworks DeepSeek XAI Mistral NIM LMStudio Cohere HuggingFace	OpenAI-protocol clients
Anthropic Gemini	native-shape clients
Vertex Bedrock	placeholders, not usable yet

Package facts

Package name	observra-sdk-node
Module format	ESM only — no CommonJS build
Node	18 or later
Peer dependency	@opentelemetry/api
Deep imports	Blocked by the exports map

Next

• Overview — the two integration paths
• Tracing — using config.tracer
• Agents and tools — multi-step runs