Skip to navigation

SDKs

An SDK (software development kit) is a library that lets your program call the IBEE API with ordinary functions instead of building HTTP requests by hand. IBEE publishes two: ibee for Python and ibee-sdk for TypeScript and JavaScript. Both are at version 0.8.0, generated from API contract 0.10.0. They cover every operation in this reference, plus the 51 temporarily paused Object Storage and Container Registry methods.

When to use an SDK

You want to…Use
Call IBEE from a Python programPython SDK: pip install ibee
Call IBEE from Node.js, a TypeScript project or a server-side JavaScript appTypeScript SDK: npm install ibee-sdk
Run one-off commands in a terminalThe CLI
Describe infrastructure in files and apply changesTerraform
Use another languageThe HTTP API

Don’t use an SDK in browser or mobile code that end users can read: the API token would be exposed.

How it works

  1. The SDKs are generated from the public API contract (the OpenAPI file behind this reference). Each API operation is one method named after its operationId: create_cloud_vm in Python, createCloudVm in TypeScript.
  2. A small hand-written layer reads your token and workspace from the environment, adds the workspace_id to each call, sends an idempotency key where the API needs one, retries safely, and turns every error answer into an exception that carries the server’s fields unchanged.
  3. The API decides everything else: prices, eligibility, limits and resource states. The SDKs send your request as you write it, fill in no defaults, and return the server’s answer.

Before you begin

Get started

1

Install the SDK

pip install --upgrade ibee
2

Set your token and workspace

export IBEE_API_TOKEN="ibee_prod_key_xxxxxxxxxxxx"
export IBEE_WORKSPACE_ID="907479"
3

Make a first call

This lists the locations where you can create VMs. It needs Virtual Machines → Read (vm.read) and creates nothing.

from ibee import Ibee
client = Ibee() # reads IBEE_API_TOKEN and IBEE_WORKSPACE_ID
for site in client.compute_catalog.list_compute_sites().sites:
print(site.site_id, site.name)

Save the TypeScript version as sites.mts and run it with npx tsx sites.mts.

4

Check the output

You see one line per site: its ID and name. An error prints the HTTP status and the server’s error code; see Troubleshooting.

Configure

Pass settings to the client, or set them in the environment. The first match wins.

SettingPythonTypeScriptEnvironment variable
TokenIbee(token=...)new Ibee({ token })IBEE_API_TOKEN, then IBEE_TOKEN
Workspaceworkspace_id=... (a call can still pass its own)workspaceId (a call can still pass workspace_id)IBEE_WORKSPACE_ID
Environmentenvironment=IbeeEnvironment.DEVELOPMENTenvironment: "dev"IBEE_ENV=dev
Base URLbase_url=...baseUrlPython: IBEE_BASE_URL, then IBEE_ENDPOINT. TypeScript: IBEE_API_URL
Timeout per requesttimeout= (default 60 seconds)timeoutInSeconds (default 60 seconds)—
Retriesmax_retries= (default 2)maxRetries (default 2)—

The default is production, https://api.ibee.ai/v1. Use the development environment only with an ibee_dev_key_… token. A base URL must use https (http only for localhost).

Create a VM

This creates a billable cloud VM. It needs Virtual Machines → Edit (vm.write).

The SDK sends only what you pass, so take the values from the catalog the way the portal does:

  • the size (cpu, ram_mb, disk_gb) from the plan;
  • os_type and os_distro from the image;
  • billing_catalog: a copy of the plan’s billing_catalog with one entry of its billing_options merged in: HOURLY, or MONTHLY for a one-month commitment.
from ibee import Ibee
client = Ibee() # IBEE_API_TOKEN and IBEE_WORKSPACE_ID from the environment
site = client.compute_catalog.list_compute_sites().sites[0]
plan = client.compute_catalog.list_compute_plans(vm_type="cloud", site_id=site.site_id).plans[0]
image = client.compute_catalog.list_compute_images(vm_type="cloud", site_id=site.site_id).images[0]
option = next(o for o in plan.billing_catalog["billing_options"] if o["billing_interval"] == "HOURLY")
billing_catalog = {**plan.billing_catalog, **option}
operation = client.cloud_vms.create_cloud_vm(
name="web-1",
site_id=site.site_id,
plan_id=plan.plan_id,
template_id=image.template_id,
os_type=image.os_type,
os_distro=image.os_distro,
cpu=plan.cpu,
ram_mb=plan.ram_mb,
disk_gb=plan.disk_gb,
billing_catalog=billing_catalog,
ssh_keys=["ssh-ed25519 AAAA... you@example.com"],
)
status = client.cloud_vms.get_compute_operation(operation.operation_id)
print(status.status) # accepted, running, ..., succeeded or failed

The create answers straight away with an operation_id; poll it until it is succeeded or failed. See Asynchronous operations. Without a term the API answers 400 compute_billing_term_required; a partial or changed entry gets 400 invalid_compute_billing_selection. A MONTHLY VM can’t be deleted or resized during its commitment (409 VM_COMMITTED). GPU VMs work the same way with vm_type="gpu", create_gpu_vm, gpu_count and gpu_model.

A few calls to know

  • Write operations that change a VM are asynchronous: poll get_compute_operation until status is succeeded or failed.
  • Resize moves the VM to another plan: resize_cloud_vm(vm_id, cpu=..., ram_mb=..., disk_gb=..., billing_catalog=...) with the target plan’s exact size and its billing_catalog, built as for a create (0.7.0 and earlier can’t send billing_catalog, so they can’t resize). The precheck, precheck_cloud_vm_resize, takes only the size.
  • get_billing_wallet() reads the organization’s wallet, and create_billing_topup(amount_minor=...) returns a payment page to top it up (billing.read and billing.topup scopes).
  • Snapshot create and backup enable take a billing_catalog from list_snapshot_storage_plans() / list_backup_storage_plans().
  • Backups disable takes an empty object: disable_cloud_vm_backups(vm_id, request={}) in Python, disableCloudVmBackups({ vm_id, body: {} }) in TypeScript.
  • VM delete sends public_ip_action only when you pass it; a VM with an automatically assigned public IP needs release or reserve. Leave it out when the VM’s IP is already a Reserved IP; both values are refused with 400.
  • Lists return the one page the API sends; pass limit and offset where the operation has them. See Lists and paging.

In Python, AsyncIbee has the same methods for asyncio. In TypeScript, add .withRawResponse() to a call to read the response headers too. The full method lists are in the Python reference.md and the TypeScript reference.md.

Errors

Every API error raises an exception that carries the HTTP status and the server’s fields exactly as sent. The SDKs add no wording of their own.

from ibee import Ibee
from ibee.core.api_error import ApiError
client = Ibee()
try:
client.cloud_vms.start_cloud_vm("VM_ID")
except ApiError as error:
print(error.status_code) # 402
print(error.code) # "billing_denied"
print(error.billing_reason) # "resource_limit_reached"
print(error.required_scope) # set with "insufficient_scope"
print(error.message) # the server's message, or None
print(error.request_id) # the x-request-id response header, if any

Each status the contract declares also has its own class, such as PaymentRequiredError, ForbiddenError, ConflictError and LockedError (in ibee.errors for Python). Branch on the status and code, not on message text. Bad configuration (no token, an unsafe base URL) raises IbeeValidationError (Python) or IbeeError (TypeScript) before anything is sent.

Retries and idempotency

  • Where the API needs an X-Idempotency-Key (a unique string that lets the API recognise a repeated request; see Idempotency), the SDK sends a random one if you pass none, and reuses it on every retry. Pass your own idempotency_key to retry a write safely across processes.
  • Reads are retried on 429, 502, 503 and 504. Writes are retried only when they carry an idempotency key: on 429 and 503 in Python, and on the same four statuses as reads in TypeScript.
  • VM creates are never retried. Python never retries an answer that carries a billing or admission code. TypeScript doesn’t check for those codes, so it can retry a 503 such as billing_admission_unavailable on a write with an idempotency key.
  • At most 2 retries by default. The wait is Retry-After when the server sends it, otherwise 1 second doubling each time with some jitter, up to 60 seconds (Python) or 30 seconds (TypeScript). 0 retries turns them off.

Upgrading from 0.7

0.8.0 follows contract 0.10.0. Resize changes: resize_cloud_vm and resize_gpu_vm (resizeCloudVm and resizeGpuVm in TypeScript) now require cpu, ram_mb, disk_gb and billing_catalog, the target plan’s exact size and its billing selection. The API already refused a resize without the catalog, so no working call breaks. The prechecks take only the size, as before. 0.8.0 adds billing.get_billing_wallet and billing.create_billing_topup (getBillingWallet and createBillingTopup), and named errors for 413 and 502.

Upgrading from 0.6

0.7.0 follows contract 0.9.0, and nothing is removed. It adds manual backup creation, queued restore cancellation and optional idempotency keys on the six networking creates. The paused Object Storage and Container Registry methods stay, and explain the empty 404.

Upgrading from 0.5

0.6.0 follows contract 0.7.1 and removes the last client-side layer: every request is sent as you write it.

  • VM create: the SDK no longer builds billing_catalog or looks up the plan and image. Pass cpu, ram_mb, disk_gb, os_type, os_distro and billing_catalog (see Create a VM). billing_term is gone.
  • VM delete, attach volume, resize: nothing is read or filled in for you. public_ip_action and the volume’s billing_catalog are sent only when you pass them; resize takes cpu, ram_mb and disk_gb (the resize-plan and resize-root-disk methods are gone).
  • Lists return one page instead of every page.
  • Removed operations (contract 0.6): manual backup runs and rescheduling, VM console sessions, mount-guidance acknowledgement, Block Storage attach and detach (use the VM’s attach and detach), CDN URL generation, subnet update, Secret Store patch and update calls, registry empty, and billing eligibility.
  • New methods for operations 0.5 didn’t have, such as Container Registry (container_registry) and bucket CORS and lifecycle rules.
  • Backups disable takes an empty object (request={} / body: {}).
  • S3 keys: revoke (POST .../revoke) keeps the record; delete removes it.
  • Token checks: the SDKs no longer compare the token’s prefix with the environment. A token sent to the other environment gets 401 invalid_api_key.

The full lists are in the Python CHANGELOG and the TypeScript CHANGELOG.

Troubleshooting

You seeWhat it meansWhat to do
No API token: pass token= or set IBEE_API_TOKEN. (Python) or No API token: pass `token` or set IBEE_API_TOKEN. (TypeScript)No token in the arguments or the environmentSet IBEE_API_TOKEN, or pass token.
401 invalid_api_keyThe token is mistyped, cut short, unknown, or for the other environmentCopy the whole token again; use the development environment only with an ibee_dev_key_ token.
403 key_expired or key_revokedThe token expired or was revokedCreate a new token.
403 insufficient_scopeThe token lacks the permission in required_scopeCreate a token with that permission.
400 workspace_id_requiredNo workspace on the client or the callSet IBEE_WORKSPACE_ID or pass workspace_id.
400 compute_billing_term_requiredVM create without a billing selectionBuild billing_catalog as in Create a VM.
TypeError: ... unexpected keyword argument 'billing_term' (Python)Code written for SDK 0.5See Upgrading from 0.5.
402 billing_deniedBilling refused a billable createRead billing_reason; see Billing refusals.
409 VM_COMMITTEDThe VM is on a Monthly commitmentWait until the commitment ends.