Reference
SDKs
Tested with:Checked-in SDK source; public package installation and release acceptance pending ZB-480.
Three SDKs for the REST API, generated from its OpenAPI document. Every
operation is a method named after its operation id: instances_list is
InstancesListWithResponse in Go, instancesList in TypeScript and instances_list in Python.
Public module/npm/PyPI publication is coming, pending ZB-480. The checked-in SDKs and release workflow do not establish that registry packages or external SDK repositories are available. The commands below use a local source checkout; registry installation examples will be enabled after publication acceptance.
From your application’s Go module, point the module path at your local SDK checkout, then resolve its dependencies:
go mod edit -replace github.com/databasezy/sdk-go=/absolute/path/to/zerobase/sdks/go# After adding your SDK imports, run: go mod tidyThe intended public module name is github.com/databasezy/sdk-go; registry availability remains pending ZB-480.
client, err := databasezy.New() // reads DATABASEZY_API_KEYif err != nil { log.Fatal(err)}page, err := client.InstancesListWithResponse(ctx, orgID, nil)if err != nil { log.Fatal(err)}for _, inst := range page.JSON200.Items { fmt.Println(inst.Id, inst.Engine, inst.Status)}Build the checked-in package from the repository root, then install that local directory in your server application:
pnpm --filter @databasezy/sdk buildnpm install /absolute/path/to/zerobase/packages/sdkThe intended registry name is @databasezy/sdk; publication remains pending ZB-480.
import { Databasezy } from "@databasezy/sdk";
const dbz = new Databasezy(); // reads DATABASEZY_API_KEYconst page = await dbz.instancesList({ org_id: orgId });for (const inst of page.items) console.log(inst.id, inst.engine, inst.status);Install the SDK from your local source checkout:
python -m pip install -e /absolute/path/to/zerobase/sdks/pythonThe intended PyPI name is databasezy; publication remains pending ZB-480.
from databasezy import Databasezy
dbz = Databasezy() # reads DATABASEZY_API_KEYfor inst in dbz.instances_list(org_id)["items"]: print(inst["id"], inst["engine"], inst["status"])Authentication
Section titled “Authentication”The SDKs authenticate with an org API key (zb_..., Organization > Access & settings > API keys or
zb api-keys create). They read it from the DATABASEZY_API_KEY environment variable (or the
CLI’s ZB_API_KEY) unless you pass it explicitly, and from nowhere else.
A project key is not an org API key: all three SDKs refuse zbp_... (publishable) and zbs_... (secret) at
construction and name the data-plane client instead, so a mixed-up key is a clear error rather than a 401.
The SDKs never log the key, send it only to the API host (not on a redirect to another
host, not to the cell when revealing credentials) and keep it out of error messages. They
only talk https; plain http is accepted for localhost alone.
Errors
Section titled “Errors”Every answer of 400 or above becomes a typed error decoded from its
problem details: the HTTP status, the problem kind
(not-found, validation, mfa_required, …), the detail, the field errors of a validation
problem and the x-request-id to quote in a support ticket.
| Status | Go (errors.Is) | TypeScript and Python |
|---|---|---|
| 400 | ErrBadRequest | BadRequestError |
| 401 | ErrUnauthorized | AuthenticationError |
| 402 | ErrPaymentRequired | PaymentRequiredError |
| 403 | ErrForbidden | PermissionDeniedError |
| 404 | ErrNotFound | NotFoundError |
| 409 | ErrConflict | ConflictError |
| 422 | ErrValidation | ValidationError |
| 429 | ErrRateLimited | RateLimitError |
| 5xx | ErrServer | InternalServerError |
Retries and idempotency
Section titled “Retries and idempotency”The SDKs retry 429, 503 and the conflicts the API marks retryable (an instance that is
waking up, a request with the same idempotency key still running), twice by default. They
wait the Retry-After the API sends (an answer asking for more than a minute is returned as
an error instead) or back off exponentially. Every POST carries an Idempotency-Key that
its retries reuse, so a retried create never creates twice; you can pass your own key.
Helpers
Section titled “Helpers”- Wait for an instance:
WaitForInstance/waitForInstance/wait_for_instancepolls until the instance isreadyand fails when it settles asfailed,deletedorpaused. - Reveal credentials:
RevealCredentials/revealCredentials/reveal_credentialsasks the API for a one-time URL and fetches it once from the instance’s cell, without the API key. A service account’s key needspurpose: "integration_env_sync"and thecredentials:reveal:integrationscope; a user session needs a recent second factor. The result prints as key names only, so logging it by mistake leaks nothing.
Each SDK has six checked-in examples, one per flow: list instances, create an instance and wait until it is
ready, print an instance’s connection info, reveal credentials into a 0600 dotenv file, list and take backups,
and read the org’s usage. Their source is under sdks/go/examples, packages/sdk/examples and
sdks/python/examples in the source checkout, and continuous integration compiles the Go ones and runs the
TypeScript and Python ones against a stub server, so they cannot drift away from the contract. This does not
imply that they are currently downloadable from public package registries.
Versions
Section titled “Versions”The checked-in generated SDK version follows the API contract version (1.0.0). Coordinated publication of the
three SDKs is planned in ZB-480 and remains unverified; a source version is not a published release. A
deprecated operation keeps working for at least 12 months; the SDKs mark it deprecated and
report the API’s Deprecation headers. See
API versioning and deprecations.