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
| Resource | Methods |
|---|
client.chat.completions | create(params) |
client.models | listDirectory(), listRegistry(), listProviders() |
client.workspaces | list(), get(workspaceId) |
client.budgets | list(workspaceId), get(workspaceId, budgetId) |
client.me | get() |
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
| Parameter | Type | Required | Description |
|---|
messages | Array<Message> | Yes | Conversation messages (non-empty) |
model | string | One of model/models | Model ID |
models | string[] | One of model/models | Model IDs for multi-model routing |
stream | boolean | No | Enable streaming (default: false) |
temperature | number | No | Sampling temperature (0–2) |
max_tokens | number | No | Max tokens to generate |
max_completion_tokens | number | No | Max completion tokens (alias for max_tokens) |
top_p | number | No | Nucleus sampling (0–1) |
frequency_penalty | number | No | Frequency penalty (-2 to 2) |
presence_penalty | number | No | Presence penalty (-2 to 2) |
stop | string | string[] | No | Stop sequences |
seed | number | No | Deterministic sampling seed |
n | number | No | Number of completions to generate |
tools | Tool[] | No | Function calling tool definitions |
tool_choice | string | object | No | Tool selection: "auto", "none", "required", or function spec |
parallel_tool_calls | boolean | No | Allow parallel function calls |
response_format | object | No | Output format (e.g., { type: "json_object" }) |
stream_options | object | No | Stream options (e.g., { include_usage: true }) |
logprobs | boolean | No | Return log probabilities |
top_logprobs | number | No | Number of top logprobs per token (0–20) |
logit_bias | Record<string, number> | No | Token bias adjustments |
user | string | No | End-user identifier |
routing | RoutingOptions | Record<string, unknown> | No | Routing configuration |
extensions | Extensions | Record<string, unknown> | No | Provider-specific extensions (thinking, passthrough) |
auriko_metadata | Record<string, unknown> | No | Request metadata (logged, visible in dashboard) |
extra_body | Record<string, unknown> | No | Additional 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 Class | HTTP Status | Error Code |
|---|
AuthenticationError | 401 | invalid_api_key |
RateLimitError | 429 | rate_limit_exceeded |
InsufficientCreditsError | 402 | insufficient_quota |
BudgetExceededError | 402 | budget_exceeded |
ModelNotFoundError | 404 | model_not_found |
InvalidRequestError | 400 | invalid_request |
ProviderError | 502 | provider_error |
ProviderAuthError | 401 | provider_auth_error |
ServiceUnavailableError | 503 | service_unavailable |
InternalError | 500 | internal_error |
AurikoAPIError Fields
| Field | Type | Description |
|---|
message | string | Human-readable error description (inherited from Error) |
statusCode | number | HTTP status code |
code | string | Machine-readable error code |
type | string | undefined | Error type category |
param | string | undefined | Parameter that caused the error |
responseHeaders | ResponseHeaders | Response 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.
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";
| Field | Type | Description |
|---|
thinking | ThinkingConfig | Extended thinking configuration (enabled, budget_tokens) |
anthropic | Record<string, unknown> | Anthropic-specific parameters |
openai | Record<string, unknown> | OpenAI-specific parameters |
google | Record<string, unknown> | Google-specific parameters |
deepseek | Record<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";