Skip to main content

TypeScript SDK Reference

See the TypeScript SDK Guide for usage examples and getting started.

Client

Initialize a client with configuration options:
import { Client } from "@auriko/sdk";

const client = new Client({
  apiKey: "sk_ia_...",                   // or AURIKO_API_KEY env var
  baseUrl: "https://api.auriko.ai/v1",  // default
  timeout: 60_000,                       // ms, default 60s
  maxRetries: 2,                         // default 2 (0 disables)
});

Resources

ResourceMethods
client.chat.completionscreate(params)
client.modelslistDirectory(), listRegistry(), listProviders()
client.workspaceslist(), get(workspaceId)
client.budgetslist(workspaceId), get(workspaceId, budgetId)
client.meget()

Chat Completions

client.chat.completions.create(params)

Creates a chat completion. Supports single-model and multi-model routing.
// Non-streaming
const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
  max_tokens: 100,
});

// Streaming
const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
});

Parameters

ParameterTypeRequiredDescription
messagesArray<Message>YesConversation messages (non-empty)
modelstringOne of model/modelsModel ID
modelsstring[]One of model/modelsModel IDs for multi-model routing
streambooleanNoEnable streaming (default: false)
temperaturenumberNoSampling temperature (0–2)
max_tokensnumberNoMax tokens to generate
max_completion_tokensnumberNoMax completion tokens (alias for max_tokens)
top_pnumberNoNucleus sampling (0–1)
frequency_penaltynumberNoFrequency penalty (-2 to 2)
presence_penaltynumberNoPresence penalty (-2 to 2)
stopstring | string[]NoStop sequences
seednumberNoDeterministic sampling seed
nnumberNoNumber of completions to generate
toolsTool[]NoFunction calling tool definitions
tool_choicestring | objectNoTool selection: "auto", "none", "required", or function spec
parallel_tool_callsbooleanNoAllow parallel function calls
response_formatobjectNoOutput format (e.g., { type: "json_object" })
stream_optionsobjectNoStream options (e.g., { include_usage: true })
logprobsbooleanNoReturn log probabilities
top_logprobsnumberNoNumber of top logprobs per token (0–20)
logit_biasRecord<string, number>NoToken bias adjustments
userstringNoEnd-user identifier
routingRoutingOptions | Record<string, unknown>NoRouting configuration
extensionsExtensions | Record<string, unknown>NoProvider-specific extensions (thinking, passthrough)
auriko_metadataRecord<string, unknown>NoRequest metadata (logged, visible in dashboard)
extra_bodyRecord<string, unknown>NoAdditional body fields (merged last, except stream)

Response (non-streaming)

interface ChatCompletion {
  id: string;
  created: number;
  model: string;
  object: "chat.completion";
  system_fingerprint?: string;
  choices: Choice[];
  usage?: Usage;
  routing_metadata?: RoutingMetadata;
  responseHeaders: ResponseHeaders;  // SDK-added
}

interface ChoiceMessage {
  role: string;
  content: string | null;
  reasoning_content?: string;  // populated by Anthropic, DeepSeek, Google, Fireworks AI
  tool_calls?: ToolCall[];
}

Response (streaming)

Returns a Stream that yields ChatCompletionChunk objects.
const stream = await client.chat.completions.create({ stream: true, ... });

for await (const chunk of stream) {
  chunk.choices[0]?.delta?.content;           // incremental content
  chunk.choices[0]?.delta?.reasoning_content; // incremental reasoning (if enabled)
}

stream.usage;            // available after iteration
stream.routing_metadata; // available after iteration
stream.responseHeaders;  // available immediately
stream.isClosed;         // boolean
stream.close();          // manual cleanup

Models

Query the model catalog:
const directory = await client.models.listDirectory();    // GET /v1/directory/models
const registry = await client.models.listRegistry();      // GET /v1/registry/models
const providers = await client.models.listProviders();    // GET /v1/registry/providers

Workspaces

List and retrieve workspaces:
const workspaces = await client.workspaces.list();        // GET /v1/workspaces
const workspace = await client.workspaces.get("ws-123");  // GET /v1/workspaces/{id}

Budgets

List and retrieve budgets:
const budgets = await client.budgets.list("ws-123");              // GET /v1/workspaces/{id}/budgets
const budget = await client.budgets.get("ws-123", "budget-456");  // GET /v1/workspaces/{id}/budgets/{bid}

Identity

Get current API key identity:
const identity = await client.me.get();  // GET /v1/me
// Returns: { object, user_id, workspace_id, tier, rate_limit_rpm }

Error Classes

All errors extend AurikoAPIError:
Error ClassHTTP StatusError Code
AuthenticationError401invalid_api_key
RateLimitError429rate_limit_exceeded
InsufficientCreditsError402insufficient_quota
BudgetExceededError402budget_exceeded
ModelNotFoundError404model_not_found
InvalidRequestError400invalid_request
ProviderError502provider_error
ProviderAuthError401provider_auth_error
ServiceUnavailableError503service_unavailable
InternalError500internal_error

AurikoAPIError Fields

FieldTypeDescription
messagestringHuman-readable error description (inherited from Error)
statusCodenumberHTTP status code
codestringMachine-readable error code
typestring | undefinedError type category
paramstring | undefinedParameter that caused the error
responseHeadersResponseHeadersResponse headers (always present)
import { Client, RateLimitError, AuthenticationError } from "@auriko/sdk";

try {
  await client.chat.completions.create({ ... });
} catch (e) {
  if (e instanceof RateLimitError) {
    console.log(e.responseHeaders.rateLimitReset);
  }
}
Providers may return additional error codes beyond those listed above. Always handle the base AurikoAPIError as a catch-all.

Response Headers

Available on both ChatCompletion.responseHeaders and Stream.responseHeaders:
response.responseHeaders.requestId;                  // X-Request-ID
response.responseHeaders.rateLimitRemaining;          // X-RateLimit-Remaining-Requests
response.responseHeaders.rateLimitLimit;              // X-RateLimit-Limit-Requests
response.responseHeaders.rateLimitReset;              // X-RateLimit-Reset-Requests
response.responseHeaders.creditsBalanceMicrodollars;  // X-Credits-Balance-Microdollars
response.responseHeaders.providerUsed;                // X-Provider-Used
response.responseHeaders.routingStrategy;             // X-Routing-Strategy
response.responseHeaders.get("x-custom-header");      // any header by name
response.responseHeaders.getAll("x-multi-header");    // string[] for multi-value headers

Constants

Runtime enum objects for routing configuration:
import { Optimize, Mode, DataPolicy } from "@auriko/sdk";

// Optimize strategy
Optimize.COST       // "cost"
Optimize.TTFT       // "ttft"
Optimize.SPEED      // "speed"
Optimize.THROUGHPUT  // "throughput"
Optimize.BALANCED   // "balanced"
Optimize.CHEAPEST   // "cheapest"

// Routing mode
Mode.POOL           // "pool"
Mode.FALLBACK       // "fallback"

// Data policy
DataPolicy.NONE         // "none"
DataPolicy.NO_TRAINING  // "no_training"
DataPolicy.ZDR          // "zdr"

Types

All types use snake_case field names matching the wire format:

Client & Stream

import { Client, Stream } from "@auriko/sdk";

Chat Response Types

import type {
  ChatCompletion, ChatCompletionChunk, Choice, ChoiceMessage,
  StreamChoice, Delta, ToolCall, ToolCallFunction,
  ToolCallDelta, ToolCallDeltaFunction,
} from "@auriko/sdk";

Common Types

import type { Usage, PromptTokensDetails, CompletionTokensDetails, ApiKeyIdentity } from "@auriko/sdk";

Routing Types

import type { RoutingOptions, RoutingMetadata, CostInfo, FallbackChainEntry } from "@auriko/sdk";

Extensions

import type { Extensions, ThinkingConfig } from "@auriko/sdk";
FieldTypeDescription
thinkingThinkingConfigExtended thinking configuration (enabled, budget_tokens)
anthropicRecord<string, unknown>Anthropic-specific parameters
openaiRecord<string, unknown>OpenAI-specific parameters
googleRecord<string, unknown>Google-specific parameters
deepseekRecord<string, unknown>DeepSeek-specific parameters
[key]Record<string, unknown>Arbitrary provider passthrough

Model Discovery Types

import type { DirectoryResponse, ModelsListResponse, ProviderList } from "@auriko/sdk";

Workspace & Budget Types

import type { Workspace, WorkspaceList, Budget, BudgetList } from "@auriko/sdk";

Request Types

import type { ChatCompletionCreateParams, ClientOptions } from "@auriko/sdk";

Runtime Constants

import { Optimize, Mode, DataPolicy, ResponseHeaders } from "@auriko/sdk";

Error Classes

import {
  AurikoAPIError, AuthenticationError, RateLimitError,
  InsufficientCreditsError, BudgetExceededError, ModelNotFoundError,
  InvalidRequestError, ProviderError, ProviderAuthError,
  ServiceUnavailableError, InternalError,
} from "@auriko/sdk";