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
Don’t use an SDK in browser or mobile code that end users can read: the API token would be exposed.
How it works
- 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_vmin Python,createCloudVmin TypeScript. - A small hand-written layer reads your token and workspace from the environment, adds the
workspace_idto 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. - 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
- Python 3.10 or later, or Node.js 18 or later.
- An API token with the permissions your program needs. See Authentication.
- Your workspace ID. See Find your workspace ID.
Get started
Make a first call
This lists the locations where you can create VMs. It needs Virtual Machines → Read (vm.read) and creates nothing.
Save the TypeScript version as sites.mts and run it with npx tsx sites.mts.
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.
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_typeandos_distrofrom the image;billing_catalog: a copy of the plan’sbilling_catalogwith one entry of itsbilling_optionsmerged in:HOURLY, orMONTHLYfor a one-month commitment.
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_operationuntilstatusissucceededorfailed. - 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 itsbilling_catalog, built as for a create (0.7.0 and earlier can’t sendbilling_catalog, so they can’t resize). The precheck,precheck_cloud_vm_resize, takes only the size. get_billing_wallet()reads the organization’s wallet, andcreate_billing_topup(amount_minor=...)returns a payment page to top it up (billing.readandbilling.topupscopes).- Snapshot create and backup enable take a
billing_catalogfromlist_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_actiononly when you pass it; a VM with an automatically assigned public IP needsreleaseorreserve. Leave it out when the VM’s IP is already a Reserved IP; both values are refused with400. - Lists return the one page the API sends; pass
limitandoffsetwhere 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.
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 ownidempotency_keyto retry a write safely across processes. - Reads are retried on
429,502,503and504. Writes are retried only when they carry an idempotency key: on429and503in 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
503such asbilling_admission_unavailableon a write with an idempotency key. - At most 2 retries by default. The wait is
Retry-Afterwhen the server sends it, otherwise 1 second doubling each time with some jitter, up to 60 seconds (Python) or 30 seconds (TypeScript).0retries 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_catalogor looks up the plan and image. Passcpu,ram_mb,disk_gb,os_type,os_distroandbilling_catalog(see Create a VM).billing_termis gone. - VM delete, attach volume, resize: nothing is read or filled in for you.
public_ip_actionand the volume’sbilling_catalogare sent only when you pass them; resize takescpu,ram_mbanddisk_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
Related pages
- CLI: the same calls from a terminal
- Terraform: infrastructure as code
- Examples: a
main.pyand anindex.tsfor every product - Authentication and API overview
