Skip to content

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:

local source checkout
go mod edit -replace github.com/databasezy/sdk-go=/absolute/path/to/zerobase/sdks/go
go mod edit -require github.com/databasezy/[email protected]
# After adding your SDK imports, run: go mod tidy

The intended public module name is github.com/databasezy/sdk-go; registry availability remains pending ZB-480.

main.go
client, err := databasezy.New() // reads DATABASEZY_API_KEY
if 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)
}

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.

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.

StatusGo (errors.Is)TypeScript and Python
400ErrBadRequestBadRequestError
401ErrUnauthorizedAuthenticationError
402ErrPaymentRequiredPaymentRequiredError
403ErrForbiddenPermissionDeniedError
404ErrNotFoundNotFoundError
409ErrConflictConflictError
422ErrValidationValidationError
429ErrRateLimitedRateLimitError
5xxErrServerInternalServerError

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.

  • Wait for an instance: WaitForInstance / waitForInstance / wait_for_instance polls until the instance is ready and fails when it settles as failed, deleted or paused.
  • Reveal credentials: RevealCredentials / revealCredentials / reveal_credentials asks 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 needs purpose: "integration_env_sync" and the credentials:reveal:integration scope; 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.

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.