Configuration

Configure the SDK globally or per-instance.

Getting Started

Quick setup guide.

Error Handling

Retry policies and error types.

Zaby client

The Zaby constructor accepts:

api_key

str | () → str | () → Awaitable[str]

required

API key for x-zaby-api-key header. Can be a static string, sync callable, or async callable.

access_token

str | () → str | () → Awaitable[str]

JWT for Authorization: Bearer header. Optional for most provisioning endpoints.

transport

ZabyTransport

Custom transport. Use MockTransport for testing.

config

ZabyGlobalConfig

Per-instance configuration overrides.

Global configuration

Set defaults shared across all client instances:

Python
TypeScript

from zaby import configure_zaby, ZabyGlobalConfig

configure_zaby(ZabyGlobalConfig(
    api_origin="https://custom.io",
    timeout_ms=60_000,
    retries=3,
    user_agent="my-app/1.0",
))

import { configureZaby } from "@zaby-ai/sdk";

configureZaby({
  apiOrigin: "https://custom.io",
  timeoutMs: 60_000,
  retries: 3,
  userAgent: "my-app/1.0",
});

Override on a single instance:

Python
TypeScript

zaby = Zaby(
    api_key="zaby_pk_...",
    config=ZabyGlobalConfig(timeout_ms=120_000),
)

import { Zaby } from "@zaby-ai/sdk";

const zaby = new Zaby({
  apiKey: "zaby_pk_...",
  config: { timeoutMs: 120_000 },
});

Instance config merges over globals — only specify the fields you want to override.

Config fields

api_origin — Base URL

type

string

default:"https://genapi.zaby.io"

Base URL for all API requests. Override for local development or custom deployments.

Python
TypeScript

ZabyGlobalConfig(api_origin="http://localhost:9080")

configureZaby({ apiOrigin: "http://localhost:9080" });

timeout_ms — Request timeout

type

int

default:"30000"

Maximum time to wait for a response, in milliseconds.

Python
TypeScript

ZabyGlobalConfig(timeout_ms=60_000)

configureZaby({ timeoutMs: 60_000 });

retries — Retry configuration

Configure which requests are retried and how.

Python
TypeScript

from zaby import RetryPolicy

ZabyGlobalConfig(retries=RetryPolicy(
    attempts=3,
    retry_methods=["GET", "HEAD", "OPTIONS"],
    retry_statuses=[408, 429, 500, 502, 503, 504],
    backoff_ms=lambda attempt: min(100 * 2 ** attempt, 1000),
))

# Integer shorthand
ZabyGlobalConfig(retries=3)

configureZaby({
  retries: {
    attempts: 3,
    retryMethods: ["GET", "HEAD", "OPTIONS"],
    retryStatuses: [408, 429, 500, 502, 503, 504],
    backoffMs: (attempt) => Math.min(100 * 2 ** attempt, 1000),
  },
});

// Integer shorthand
configureZaby({ retries: 3 });

user_agent — Custom User-Agent

Python
TypeScript

ZabyGlobalConfig(user_agent="my-app/1.0")

configureZaby({ userAgent: "my-app/1.0" });

environment — Environment preset

type

string

default:"production"

Sets a preset origin. “local” → http://localhost:9080

Retry policy

attempts

int

default:"0"

Maximum retry attempts

retry_methods

string[]

default:"[\"GET\", \"HEAD\", \"OPTIONS\"]"

HTTP methods eligible for retry

retry_statuses

int[]

default:"[408, 429, 500, 502, 503, 504]"

Status codes that trigger a retry

backoff_ms

callable

default:"exponential 100ms–1s"

Delay function: lambda attempt: min(100 * 2**attempt, 1000)

Only idempotent methods (GET, HEAD, OPTIONS) are retried by default. POST and other mutating methods are not retried to prevent duplicate operations.

Authentication providers

Credentials can be static strings, lazy callables, or async callables:

Python
TypeScript

# Static string
zaby = Zaby(api_key="zaby_pk_static_key")

# Lazy — called on every request
zaby = Zaby(api_key=lambda: get_current_key())

# Async
async def key_provider() -> str:
    return await fetch_key_from_vault()
zaby = Zaby(api_key=key_provider)

import { Zaby } from "@zaby-ai/sdk";

// Static string
const zaby = new Zaby({ apiKey: "zaby_pk_static_key" });

// Lazy — called on every request
const lazy = new Zaby({ apiKey: () => getCurrentKey() });

// Async provider
const asyncClient = new Zaby({
  apiKey: async () => fetchKeyFromVault(),
});

Environment variables

# .env or shell
export ZABY_API_ORIGIN=http://192.168.68.61:9080
export ZABY_ENVIRONMENT=local

Explicit api_origin always takes precedence over environment presets.

Resolve configuration

The SDK resolves effective config by merging overrides → global config → env vars → defaults. The resolve function is useful when you want to inspect the final config without creating a client:

Python
TypeScript

from zaby import resolve_zaby_config, ZabyGlobalConfig

# Returns ResolvedZabyConfig with all defaults filled in
config = resolve_zaby_config(ZabyGlobalConfig(timeout_ms=60_000))
print(config.api_origin)  # "https://genapi.zaby.io"
print(config.timeout_ms)  # 60000

import { configureZaby } from "@zaby-ai/sdk";

// Per-instance config merges over globals on construction
const zaby = new Zaby({
  apiKey: "...",
  config: { timeoutMs: 60_000 },
});
// No public resolve function — config is resolved internally

ZabyRuntime options

token

str | () → str | () → Awaitable[str]

required

JWT runtime token for Authorization: Bearer

transport

ZabyTransport

Custom transport for testing.

config

ZabyGlobalConfig

Runtime-specific config overrides.

Python
TypeScript

from zaby import ZabyRuntime

runtime = ZabyRuntime(token="eyJhbGciOi...")

import { ZabyRuntime } from "@zaby-ai/sdk/runtime";

const runtime = new ZabyRuntime({ token: "eyJhbGciOi..." });

Request options

Per-request options for fine-grained control:

request_id

str

Custom request ID for idempotency and tracing

signal

AbortSignal

Cancellation signal to abort in-flight requests

Python
TypeScript

from zaby import RequestOptions

await zaby.agents.create(
    {"name": "my-agent", "slug": "my-agent"},
    options=RequestOptions(request_id="my-id"),
)

await zaby.agents.create(
  { name: "my-agent", slug: "my-agent" },
  { requestId: "my-id" },
);

List response

Paginated list operations return a ListResponse wrapper:

items

array

Result items

page

int

Current page number

limit

int

Items per page

total

int

Total item count

Getting Started

Clients

Guides

Configuration

Configuration

Getting Started

Error Handling

Zaby client

Global configuration

Config fields

Retry policy

Authentication providers

Environment variables

Resolve configuration

ZabyRuntime options

Request options

List response

​Configuration

Getting Started

Error Handling

​Zaby client

​Global configuration

​Config fields

​Retry policy

​Authentication providers

​Environment variables

​Resolve configuration

​ZabyRuntime options

​Request options

​List response

Configuration

Zaby client

Global configuration

Config fields

Retry policy

Authentication providers

Environment variables

Resolve configuration

ZabyRuntime options

Request options

List response