Getting Started

Install the Zaby SDK and make your first API call. Provisioning a deployment takes roughly 12 minutes.

Switch between Python and TypeScript code examples using the language tabs.

Reference

Full API reference for all clients.

Configuration

Timeouts, retries, auth providers.

Prerequisites

Python 3.10 or later, or Node 20+
A Zaby account with an API key (zaby_pk_...)

Install

Python
TypeScript

pip install git+https://github.com/ZABY-AI/zaby-sdk-python.git

npm install @zaby-ai/sdk

Create a client

Create an API key

Generate an API key in the Zaby dashboard. Keys start with zaby_pk_.

Initialize the client

Python
TypeScript

from zaby import Zaby

zaby = Zaby(api_key="zaby_pk_your_key_here")

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

const zaby = new Zaby({
  apiKey: "zaby_pk_your_key_here",
});

Verify the connection

Python
TypeScript

health = await zaby.health.check()
# {"status": "ok", "timestamp": "2026-06-24T12:00:00Z", "uptime": 1234.56}

const health = await zaby.health.check();
// {status: "ok", timestamp: "2026-06-24T12:00:00Z", uptime: 1234.56}

No authentication is required for health checks.

Create an agent

Python
TypeScript

agent = await zaby.agents.create({
    "name": "Support Agent",
    "slug": "support-agent",
    "description": "Handles customer support inquiries",
})

const agent = await zaby.agents.create({
  name: "Support Agent",
  slug: "support-agent",
  description: "Handles customer support inquiries",
});

string

Agent identifier

status

string

Always “DRAFT” initially

✓ Agent created: a1b2c3d4-...
✓ Status: DRAFT

Extract the agent ID for use in subsequent steps:

Python
TypeScript

agent_id = agent["id"]

const agent_id = agent.id;

Publish and deploy

Publish

Creates a version snapshot of the agent.

Python
TypeScript

version = await zaby.agents.publish(agent_id)
version_id = version["id"]

const version = await zaby.agents.publish(agent_id);
const version_id = version.id;

Deploy

Use "TEST" environment. Deployments take ~12 minutes to become active.

Python
TypeScript

deployment = await zaby.deployments.create(agent_id, {
    "agentVersionId": version_id,
    "environment": "TEST",
})
deployment_id = deployment["id"]

const deployment = await zaby.deployments.create(agent_id, {
  agentVersionId: version_id,
  environment: "TEST",
});
const deployment_id = deployment.id;

The deployment returns immediately with status PENDING. Cloudflare provisioning runs in the background and transitions to ACTIVE after roughly 12 minutes. Calling getProvisioning() before it’s ACTIVE returns 404.

Create an external app and bind deployment

The external app represents your application. Binding requires allowServerRuntime: true for server-side access (needed for ZabyRuntime).

Python
TypeScript

app = await zaby.external_apps.create({
    "name": "My App",
    "slug": "my-app",
    "allowedOrigins": ["http://localhost:3000"],
})

await zaby.external_apps.bind_deployment(app["id"], {
    "deploymentId": deployment_id,
    "allowServerRuntime": True,
})

const app = await zaby.externalApps.create({
  name: "My App",
  slug: "my-app",
  allowedOrigins: ["http://localhost:3000"],
});

await zaby.externalApps.bindDeployment(app.id, {
  deploymentId: deployment_id,
  allowServerRuntime: true,
});

Create a quota policy

A quota policy is required before generating runtime tokens. Without it, token creation fails with a 500 error.

Python
TypeScript

policy = await zaby.runtime_token_policies.create({
    "name": "Default Policy",
    "externalAppId": app["id"],
    "deploymentId": deployment_id,
    "maxConcurrentRuns": 10,
    "tokenTtlSeconds": 3600,
    "maxUsesPerToken": 50,
})
policy_id = policy["id"]

const policy = await zaby.runtimeTokenPolicies.create({
  name: "Default Policy",
  externalAppId: app.id,
  deploymentId: deployment_id,
  maxConcurrentRuns: 10,
  tokenTtlSeconds: 3600,
  maxUsesPerToken: 50,
});
const policy_id = policy.id;

Generate a runtime token

Pass quotaPolicyId — the token will be rejected without it.

Python
TypeScript

token = await zaby.runtime_tokens.create({
    "externalAppId": app["id"],
    "deploymentId": deployment_id,
    "quotaPolicyId": policy_id,
    "externalUserId": "user-1",
    "externalSessionId": "session-1",
    "channel": "server",
    "ttlSeconds": 600,
})
runtime_token = token["token"]

const token = await zaby.runtimeTokens.create({
  externalAppId: app.id,
  deploymentId: deployment_id,
  quotaPolicyId: policy_id,
  externalUserId: "user-1",
  externalSessionId: "session-1",
  channel: "server",
  ttlSeconds: 600,
});
const runtime_token = token.token;

Next steps

Configuration Guide

Timeouts, retries, auth providers, and environment setup.

Agents Client

Full agent lifecycle reference.

Runtime Client

Start runs and stream agent responses.

Error Handling

Error types, status codes, and retry strategies.

Getting Started

Clients

Guides

Getting Started

Getting Started

Reference

Configuration

Prerequisites

Install

Create a client

Create an agent

Publish and deploy

Next steps

Configuration Guide

Agents Client

Runtime Client

Error Handling

​Getting Started

Reference

Configuration

​Prerequisites

​Install

​Create a client

​Create an agent

​Publish and deploy

​Next steps

Configuration Guide

Agents Client

Runtime Client

Error Handling

Getting Started

Prerequisites

Install

Create a client

Create an agent

Publish and deploy

Next steps