Official SDKs (JavaScript, Python and Go)

What they are

@vertracloud/sdk-api (JavaScript/TypeScript), vertracloud-api (Python) and github.com/vertracloud/sdk-api-go (Go) are thin typed clients over the public API: one method per route, the same API key scopes, and nothing beyond that — no cache, no automatic retry, no state of its own. Use them instead of hand-rolling fetch/requests/net/http when you want types and errors already structured.

Installation

npm install @vertracloud/sdk-api

pip install vertracloud-api

go get github.com/vertracloud/sdk-api-go

Authentication

All three clients take the API key at construction — the same key created under Settings → API keys in the dashboard, with the scopes your code will use (see Scopes).

import { VertraClient } from "@vertracloud/sdk-api";

const client = new VertraClient({ apiKey: process.env.VERTRA_API_KEY! });

import os

from vertracloud import VertraClient

client = VertraClient(api_key=os.environ["VERTRA_API_KEY"])

import (
	"github.com/vertracloud/sdk-api-go/rest"
	"github.com/vertracloud/sdk-api-go/vertracloud"
)

restClient, err := rest.NewClient(os.Getenv("VERTRA_API_KEY"))
if err != nil {
	log.Fatal(err)
}
client := vertracloud.New(restClient)

All of them accept an optional base URL and timeout (baseUrl/timeoutMs, base_url/timeout, rest.WithBaseURL/rest.WithTimeout); the default already points to https://api.vertracloud.app. In Go, every call takes context.Context first and per-call options at the end — for example, rest.WithWorkspaceID(id) to act on a workspace resource.

Examples by domain

Applications

const app = await client.apps.get("app-abc123");
await client.apps.restart("app-abc123");
const runtimes = await client.apps.runtimes();

app = client.apps.get("app-abc123")
client.apps.restart("app-abc123")
runtimes = client.apps.runtimes()

app, err := client.Apps.Get(ctx, "app-abc123")
_, err = client.Apps.Restart(ctx, "app-abc123", nil)
runtimes, err := client.Apps.Runtimes(ctx)

restart also takes optional reinstall_dependencies and force_build flags (for example { force_build: true } in JavaScript); a restart that sets either one runs a build and counts against the plan’s deploys-per-hour limit. Creating an application answers right away with status: "building"; the build continues in the background. Wait for it to finish with the helper for your language. It returns the application once it is up and raises an error if the build ended down (the error code is the application’s last_build_error, such as INSTALL_OUT_OF_MEMORY, or APP_DOWN when none; read the logs for the detail) or the wait ran out.

const app = await client.apps.create({ file: zip, name: "bot", memory: 256 });
const ready = await client.apps.waitUntilReady(app.id, { timeoutMs: 600_000, intervalMs: 2_000 });
// throws AppBuildFailedError (ended down) or AppBuildTimeoutError; also accepts signal and workspaceId

ready = client.apps.wait_until_ready(app_id, timeout=600.0, interval=2.0)
# raises AppBuildFailedError (ended down) or WaitTimeoutError; also accepts workspace_id

ready, err := client.Apps.WaitUntilReady(ctx, app.ID, &vertracloud.WaitOptions{Interval: 2 * time.Second})
// *vertracloud.AppNotReadyError when the build ended down; ctx bounds the wait

Releases and rollback

Listing releases and reading a log need apps:read. The preview needs apps:envs and returns only variable names, never values. A rollback needs apps:write, plus apps:envs to restore variables, and is available on every plan. See the guide for what a rollback restores.

const { data } = await client.apps.releases.list("app-abc123", { limit: 10 });
const target = data.find((r) => r.status !== "active" && r.rollback.available);

const preview = await client.apps.releases.previewRollback("app-abc123", target.id);
await client.apps.releases.rollback("app-abc123", target.id, { restore_environment: false });

page = client.apps.releases.list("app-abc123", limit=10)
target = next(r for r in page["data"] if r["status"] != "active" and r["rollback"]["available"])

preview = client.apps.releases.preview_rollback("app-abc123", target["id"])
client.apps.releases.rollback("app-abc123", target["id"], {"restore_environment": False})

page, err := client.Apps.Releases().List(ctx, "app-abc123", vertracloud.ApplicationReleasesListParams{})
// pick releaseID from page, then:
preview, err := client.Apps.Releases().Preview(ctx, "app-abc123", releaseID)
_, err = client.Apps.Releases().Rollback(ctx, "app-abc123", releaseID, vertracloud.ApplicationRollbackBody{})

Deploy settings go through the application’s configuration. A message on an upload appears in the release history.

await client.apps.updateConfig("app-abc123", {
  deploy: { zero_downtime: "auto", auto_rollback: true, health_check_path: "/health" },
});
await client.apps.files.upload("app-abc123", zip, "app.zip", { message: "fix login" });

client.apps.update_config(
    "app-abc123",
    {"deploy": {"zero_downtime": "auto", "auto_rollback": True, "health_check_path": "/health"}},
)
client.apps.files.upload("app-abc123", file=zip_bytes, filename="app.zip", message="fix login")

off := vertracloud.ApplicationZeroDowntimeOff
_, err = client.Apps.UpdateConfig(ctx, "app-abc123", vertracloud.ApplicationUpdateConfigBody{
	Deploy: &vertracloud.ApplicationDeploySettingsUpdate{
		ZeroDowntime:    &off,
		HealthCheckPath: vertracloud.NullableValue("/health"),
	},
})
// uploads: client.Apps.Files().Upload(ctx, "app-abc123", vertracloud.ApplicationFileUploadParams{..., Message: "fix login"})

Databases

const db = await client.databases.get("db-abc123");
await client.databases.start("db-abc123");

db = client.databases.get("db-abc123")
client.databases.start("db-abc123")

db, err := client.Databases.Get(ctx, "db-abc123")
_, err = client.Databases.Start(ctx, "db-abc123")

Snapshots

The scope ("applications" or "databases") is required on every snapshot call — the same resource ID could be an app or a database, and the API doesn’t guess.

const snapshots = await client.snapshots.list("app-abc123", { scope: "applications" });
const created = await client.snapshots.create("app-abc123", { scope: "applications" });
await client.snapshots.restore("app-abc123", created.id, { scope: "applications" });

snapshots = client.snapshots.list("app-abc123", scope="applications")
created = client.snapshots.create("app-abc123", scope="applications")
client.snapshots.restore("app-abc123", created["id"], scope="applications")

snapshots, err := client.Snapshots.List(ctx, "app-abc123", vertracloud.SnapshotScopeApplications)
created, err := client.Snapshots.Create(ctx, "app-abc123", vertracloud.SnapshotScopeApplications)
_, err = client.Snapshots.Restore(ctx, "app-abc123", created.ID, vertracloud.SnapshotScopeApplications)

Account

const me = await client.account.get();
const sessions = await client.account.sessions.list();

me = client.account.get()
sessions = client.account.sessions.list()

me, err := client.Account.Get(ctx)
sessions, err := client.Account.Sessions().List(ctx)

Workspaces

const members = await client.workspaces.members.list("ws-abc123");
await client.workspaces.apps.add("ws-abc123", "app-abc123");

members = client.workspaces.members.list("ws-abc123")
client.workspaces.apps.add("ws-abc123", "app-abc123")

members, err := client.Workspaces.Members().List(ctx, "ws-abc123")
err = client.Workspaces.Apps().Add(ctx, "ws-abc123", "app-abc123")

Billing and redemption

const order = await client.billing.orders.create({ type: "purchase", plan: "pro", months: 1 });
const pix = await client.billing.orders.initiatePix(order.id);

order = client.billing.orders.create({"type": "purchase", "plan": "pro", "months": 1})
pix = client.billing.orders.initiate_pix(order["id"])

order, err := client.Billing.Orders().Create(ctx, vertracloud.OrderCreateBody{
	Type: vertracloud.OrderTypePurchase, Plan: "pro", Months: 1,
})
pix, err := client.Billing.Orders().InitiatePix(ctx, order.ID)

Before creating an order, the account needs complete billing details (name, address and, in Brazil, CPF/CNPJ), otherwise orders.create fails with BILLING_DETAILS_INCOMPLETE. Read them with billing.details (client.Billing.Details in Go) and save them with billing.updateDetails (update_details in Python, client.Billing.UpdateDetails in Go), using keys with the billing:read and billing:write scopes. To redeem a promo code, use billing.redeem (client.billing.redeem(code) in JavaScript and Python, client.Billing.Redeem(ctx, code) in Go), with a key that has the redeem:write scope.

Web Analytics

const traffic = await client.apps.analytics.traffic("app-abc123", { compare: true });
const errors = await client.apps.analytics.errors("app-abc123", { include_4xx: true });
const lastWeek = await client.apps.analytics.errors("app-abc123", { start: "2026-11-02T00:00:00Z", compare_start: "2026-10-26T00:00:00Z" });
const perf = await client.apps.analytics.performance("app-abc123");
for await (const request of client.apps.analytics.requestsAll("app-abc123", { status: "5xx" })) {
  console.log(request.request_id);
}

traffic = client.apps.analytics.traffic("app-abc123", compare=True)
errors = client.apps.analytics.errors("app-abc123", include_4xx=True)
last_week = client.apps.analytics.errors("app-abc123", start="2026-11-02T00:00:00Z", compare_start="2026-10-26T00:00:00Z")
perf = client.apps.analytics.performance("app-abc123")
for request in client.apps.analytics.iter_requests("app-abc123", status="5xx"):
    print(request["request_id"])

analytics := client.Apps.Analytics()
traffic, err := analytics.Traffic(ctx, "app-abc123", &vertracloud.ApplicationAnalyticsTrafficParams{Compare: true})
errs, err := analytics.Errors(ctx, "app-abc123", nil)
lastWeek, err := analytics.Errors(ctx, "app-abc123", &vertracloud.ApplicationAnalyticsErrorsParams{
    ApplicationAnalyticsRange: vertracloud.ApplicationAnalyticsRange{Start: time.Now().Add(-24 * time.Hour)},
    CompareStart:              time.Now().Add(-8 * 24 * time.Hour),
})
perf, err := analytics.Performance(ctx, "app-abc123", nil)
it := analytics.RequestsIter("app-abc123", nil)
for it.Next(ctx) {
    fmt.Println(it.Request().RequestID)
}

All four calls need apps:read. They take the period (start, end), the filters of each dimension and compare. performance and requests fail with PLAN_DOES_NOT_SUPPORT_WEB_ANALYTICS_PERFORMANCE and PLAN_DOES_NOT_SUPPORT_WEB_ANALYTICS_REQUESTS when the plan does not include them; a period before the plan’s history fails with ANALYTICS_RANGE_EXCEEDS_PLAN and a busy moment with ANALYTICS_BUSY (the typed error exposes the wait in seconds).

Blob Storage

File storage has its own SDK, @vertracloud/blob, for Node, browsers and edge runtimes (npm install @vertracloud/blob). In Python and Go it is a resource of the same client: client.blob and client.Blob. See JavaScript SDK and Python and Go SDKs.

Streaming (`apps.realtime`)

GET /v1/apps/{id}/realtime is the only route in the catalog that streams live events (logs and system notes). JavaScript exposes an async generator; Python, an iterable stream object; Go, an iterator (Next/Event/Err) — none of them reconnect on their own if the connection drops.

for await (const event of client.apps.realtime("app-abc123")) {
  console.log(event.event, event.data);
}

with client.apps.realtime("app-abc123") as stream:
    for event in stream:
        print(event.event, event.data)

stream, err := client.Apps.Realtime(ctx, "app-abc123", nil)
if err != nil {
	log.Fatal(err)
}
defer stream.Close()

for stream.Next(ctx) {
	event := stream.Event()
	fmt.Println(event.Event, event.Data)
}
if err := stream.Err(); err != nil {
	log.Fatal(err)
}

Typed errors

Every response outside the 2xx range becomes a structured error, always with code (and details, when the API sends it) accessible — never a loose string to parse. In JavaScript and Python, the exception class indicates the HTTP status; in Go, every API error is a single *rest.APIError, and the status is checked through methods.

Status	JavaScript	Python	Go (`*rest.APIError`)
401	`AuthenticationError`	`AuthenticationError`	`IsAuthenticationError()`
403	`PermissionError`	`ScopeDeniedError`	`IsPermissionError()`
404	`NotFoundError`	`NotFoundError`	`IsNotFoundError()`
400 / 422	`ValidationError`	`ValidationError`	`IsValidationError()`
429	`RateLimitError`	`RateLimitError`	`IsRateLimitError()`
other	`VertraAPIError`	`VertraAPIError`	`Status` field

JavaScript

import { RateLimitError } from "@vertracloud/sdk-api";

try {
  await client.apps.restart("app-abc123");
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter}s`);
  }
  throw error;
}

Python

from vertracloud.errors import RateLimitError

try:
    client.apps.restart("app-abc123")
except RateLimitError as error:
    print(f"Retry after {error.retry_after}s")
    raise

_, err := client.Apps.Restart(ctx, "app-abc123", nil)
if apiErr, ok := rest.AsAPIError(err); ok && apiErr.IsRateLimitError() {
	if wait := apiErr.RetryAfter(); wait != nil {
		fmt.Printf("Retry after %s\n", *wait)
	}
}

None of the clients print the API key to logs, toString()/__repr__/Error(), or error serialization — retry_after (in seconds) comes from details.retry_after in the error body or the Retry-After header on 429 responses. See Rate Limiting for per-route limits.

What you can’t do with an API key

Some management actions are only available in the dashboard, and are therefore not exposed by the SDKs:

Resource	Where it lives
Account/workspace activity	Dashboard → Activity
Notifications	Dashboard → Notifications
API key management (create, list, rotate, revoke)	Dashboard → Settings → API keys
Creating a workspace invite, transferring ownership, approving/rejecting an action request	Dashboard → Workspace
Database Data tab (schemas, tables, SQL console, collections, keys)	Dashboard → Database → Data
Plan downgrade	Dashboard → Plan

For AI agent automation over files, logs, apps and deploys, see the MCP server — it uses the same API key, with the same scope model.

​What they are

​Installation

​Authentication

​Examples by domain

​Applications

​Releases and rollback

​Databases

​Snapshots

​Account

​Workspaces

​Billing and redemption

​Web Analytics

​Blob Storage

​Streaming (apps.realtime)

​Typed errors

​What you can’t do with an API key