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 Create a client
Initialize the client
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
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 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" , });
✓ Agent created: a1b2c3d4-... ✓ Status: DRAFT
Extract the agent ID for use in subsequent steps:
const agent_id = agent . id ;
Publish and deploy
Publish
Creates a version snapshot of the agent. 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. 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). 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. 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. 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.
