> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ibee.co.in/docs/api-reference/sdk-overview/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ibee.co.in/_mcp/server.

# SDKs

> Official SDKs for the IBEE Solutions API.

Official client libraries for the IBEE Solutions API. Install one for your language and start building.

| Tool                           | Install                | Language            |
| ------------------------------ | ---------------------- | ------------------- |
| Python SDK                     | `pip install ibee`     | Python 3.10+        |
| TypeScript SDK                 | `npm install ibee-sdk` | Node 18+ / browsers |
| [CLI](/docs/api-reference/cli) | `pip install ibee-cli` | Terminal            |

Version 0.3 covers object storage, secret store, compute discovery, cloud and
GPU VMs, VPC networking, Reserved IPs, firewalls, load balancers, Block
Storage, CDN, and an
explicit billing eligibility check. Every client authenticates with an API
token from **Settings → API Tokens** plus a workspace ID.

## Environments

The SDKs target **production** (`https://api.ibee.ai/v1`) by default. To use the development gateway (`https://api.ibee.co.in/v1`) with a `ibee_dev_key_...` token:

**`Python`**

```python title="Python"
from ibee import Ibee, IbeeEnvironment

client = Ibee(token="ibee_dev_key_xxx", environment=IbeeEnvironment.DEVELOPMENT)
```

**`TypeScript`**

```typescript title="TypeScript"
import { Ibee, IbeeEnvironment } from "ibee-sdk";

const client = new Ibee({ token: "ibee_dev_key_xxx", environment: IbeeEnvironment.DEVELOPMENT });
```

## Billing admission on create

The Python SDK, TypeScript SDK, and CLI expose the billing eligibility endpoint
as an explicit preflight. They do not call it automatically before create
requests. When your workflow needs an early decision, call the eligibility
operation immediately before creating the resource and continue only when
`allowed` is `true`.

The preflight token needs `billing.read`; the create request needs the relevant
product write scope. The public gateway is authoritative and performs a
fail-closed billing decision before forwarding every declared billable create
to the existing product service. A successful earlier preflight is not a
reservation or a guarantee that a later create will succeed.

## Python SDK

Install the Python SDK from PyPI:

```bash
pip install ibee
```

```python
from ibee import Ibee

client = Ibee(token="ibee_prod_key_xxxxxxxxxxxx")

# Discover IDs accepted by VM creation
sites = client.compute_catalog.list_compute_sites(workspace_id="907479")
plans = client.compute_catalog.list_compute_plans(
    workspace_id="907479", vm_type="cloud"
)
images = client.compute_catalog.list_compute_images(
    workspace_id="907479", vm_type="cloud"
)

# List cloud VMs
vms = client.cloud_vms.list_cloud_vms(workspace_id="907479")

# Create a cloud VM from a priced plan and an image
plan = next(p for p in plans.plans if p.selectable and p.pricing_status == "priced")
image = images.images[0]
vm = client.cloud_vms.create_cloud_vm(
    workspace_id="907479",
    idempotency_key="create-web-server-01",
    name="web-server",
    plan_id=plan.plan_id,
    template_id=image.template_id,
    os_distro=image.os_distro,
    os_type=image.os_type,
    cpu=plan.cpu,
    ram_mb=plan.ram_mb,
    # Pass the plan's billing_catalog through unchanged (see below).
    request_options={"additional_body_parameters": {"billing_catalog": plan.billing_catalog}},
)

# List GPU VMs
gpu_vms = client.gpu_vms.list_gpu_vms(workspace_id="907479")

# Object storage — list and create
buckets = client.object_storage.list_buckets(workspace_id="907479")
bucket = client.object_storage.create_bucket(
    workspace_id="907479", name="my-bucket", region="in-south-2"
)

# Secret store — create a store, then a versioned secret
store = client.secret_store.create_secret_store(workspace_id="907479", name="payments")
secret = client.secret_store.create_secret(
    workspace_id="907479",
    store_id=store.id,
    secret_name="stripe-key",
    value={"API_KEY": "sk_live_xxx"},
)
value = client.secret_store.get_secret_value(workspace_id="907479", secret_id=secret.id)
```

To create a VM from the same kind of choices shown in the portal, pass the
selected IDs into the create call:

```python
vm = client.cloud_vms.create_cloud_vm(
    workspace_id="907479",
    idempotency_key="create-web-server-01",
    name="web-server-01",
    os_distro="ubuntu",
    os_type="linux",
    template_id="tmpl_ubuntu_2204",
    plan_id="plan_standard_2c_4g",
    cpu=2,
    ram_mb=4096,
    disk_gb=80,
    ssh_key_ids=["ssh_key_123"],
    tags=["prod", "web"],
    request_options={"additional_body_parameters": {"billing_catalog": plan.billing_catalog}},
)
```

`plan_id` is the selected instance plan. `template_id` is the selected OS
template or image. `ssh_key_ids` are the SSH keys to inject at first boot.
`billing_catalog` is the object returned with the selected plan by
`list_compute_plans`; the API requires it on every VM create and it must be
sent back unchanged. SDK 0.3.0 has no named argument for it yet, so pass it as
an additional body parameter as shown.
Omit `site_id` for automatic placement. To pin a VM, copy the exact `site_id`
returned by `list_compute_sites`; do not use a region or site name.
In the current SDK, `cpu` and `ram_mb` are still required fallback fields even
when `plan_id` is provided.

**Async support** is built in:

```python
import asyncio
from ibee import AsyncIbee

async def main():
    client = AsyncIbee(token="ibee_prod_key_xxxxxxxxxxxx")
    vms = await client.cloud_vms.list_cloud_vms(workspace_id="907479")
    print(vms)

asyncio.run(main())
```

#### [Python SDK on GitHub](https://github.com/devs-ibee/ibee-python)

#### [Python SDK on PyPI](https://pypi.org/project/ibee/)

## TypeScript SDK

Install the TypeScript SDK from npm. It works in Node 18+ and modern browsers, ships ESM and CommonJS builds with full type declarations, and has no runtime dependencies.

```bash
npm install ibee-sdk
```

```typescript
import { Ibee } from "ibee-sdk";

const client = new Ibee({ token: "ibee_prod_key_xxxxxxxxxxxx" });

const sites = await client.computeCatalog.listSites({ workspaceId: "907479" });
const plans = await client.computeCatalog.listPlans({
  workspaceId: "907479",
  vmType: "cloud",
});
const images = await client.computeCatalog.listImages({
  workspaceId: "907479",
  vmType: "cloud",
});

// List cloud VMs
const vms = await client.cloudVms.list({ workspaceId: "907479" });

// Create a cloud VM from a priced plan and an image
const plan = plans.plans.find((p) => p.selectable && p.pricing_status === "priced")!;
const image = images.images[0];
await client.cloudVms.create({
  workspaceId: "907479",
  name: "web-server",
  plan_id: plan.plan_id,
  template_id: image.template_id,
  os_distro: image.os_distro,
  os_type: image.os_type,
  cpu: plan.cpu,
  ram_mb: plan.ram_mb,
  // SDK 0.3.0 has no billing_catalog field yet; pass the plan's object through unchanged.
  ...{ billing_catalog: (plan as typeof plan & { billing_catalog: unknown }).billing_catalog },
});

// List buckets
const buckets = await client.objectStorage.listBuckets({ workspaceId: "907479" });

// Create a bucket in an Object Storage region
const bucket = await client.objectStorage.createBucket({
  workspaceId: "907479",
  name: "my-bucket",
  region: "in-south-2",
});
```

Non-2xx responses throw an `ApiError` carrying the HTTP status and parsed body:

```typescript
import { ApiError } from "ibee-sdk";

try {
  await client.secretStore.listSecretStores({ workspaceId: "907479" });
} catch (err) {
  if (err instanceof ApiError) {
    console.error(err.statusCode, err.body);
  }
}
```

#### [TypeScript SDK on GitHub](https://github.com/devs-ibee/ibee-typescript)

#### [ibee-sdk on npm](https://www.npmjs.com/package/ibee-sdk)

## Billing eligibility preflight

Before a billable create, ask billing whether the workspace is allowed to
create the SKU. Proceed only when `allowed` is `true`; the token needs
`billing.read` in addition to the product write scope.

**`Python`**

```python title="Python"
eligibility = client.billing.check_resource_eligibility(
    workspace_id="907479", sku_code="OBJECTST-STD"
)
if not eligibility.allowed:
    raise RuntimeError(f"Blocked by billing: {eligibility.reason}")

bucket = client.object_storage.create_bucket(
    workspace_id="907479", name="my-bucket"
)
```

**`TypeScript`**

```typescript title="TypeScript"
const eligibility = await client.billing.checkResourceEligibility({
  workspaceId: "907479",
  skuCode: "OBJECTST-STD",
});
if (!eligibility.allowed) {
  throw new Error(`Blocked by billing: ${eligibility.reason}`);
}

const bucket = await client.objectStorage.createBucket({
  workspaceId: "907479",
  name: "my-bucket",
});
```

**`CLI`**

```bash title="CLI"
ibee billing eligibility OBJECTST-STD
```

The decision is point-in-time and does not reserve funds, so run it
immediately before the create request. The SDKs and CLI do not invoke it
automatically.

## Command-line interface

Prefer the terminal? The `ibee` CLI is built on the Python SDK and covers the same products.

```bash
pip install ibee-cli
export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx"
export IBEE_WORKSPACE_ID="907479"

ibee buckets list
ibee buckets create my-bucket --region in-south-2
ibee secrets stores list
ibee compute sites
ibee vpcs list
ibee vms list
```

See the [CLI reference](/docs/api-reference/cli) for all commands.

## Resource reference

Both SDKs expose the same resources (Python uses `snake_case`, TypeScript uses `camelCase`):

| Resource        | Operations                                                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| Object storage  | bucket list, create, get, update, delete · S3 credential list, create, get, revoke                         |
| Secret store    | stores (create, list, get, update, archive) · secrets (create, list, get, get value, update value, delete) |
| Compute catalog | list placement sites, billable plans, and compatible images                                                |
| Cloud VMs       | list, get, create, delete, start, stop, reboot, metrics                                                    |
| GPU VMs         | list, get, create, delete, start, stop, reboot, metrics                                                    |
| VPCs            | sites, VPCs, subnets, VM attachments, NAT gateways, port-forwarding rules                                  |
| Reserved IPs    | list, reserve, get, update, release, attach, detach, move                                                  |
| Firewalls       | group, rule, and VM attachment lifecycle                                                                   |
| Load balancers  | L4/L7 lifecycle and provisioning status                                                                    |
| Billing         | check resource eligibility before a billable create                                                        |
| Operations      | get (poll async operation status)                                                                          |

## Using the API without an SDK

You can call the REST API directly using any HTTP client:

**`cURL`**

```bash title="cURL"
curl https://api.ibee.ai/v1/object-storage/buckets?workspace_id=907479 \
  -H "Authorization: Bearer ibee_prod_key_xxxxxxxxxxxx"
```

**`Python (requests)`**

```python title="Python (requests)"
import requests

resp = requests.get(
    "https://api.ibee.ai/v1/object-storage/buckets",
    params={"workspace_id": "907479"},
    headers={"Authorization": "Bearer ibee_prod_key_xxxxxxxxxxxx"},
)
buckets = resp.json()
```

**`Node.js (fetch)`**

```javascript title="Node.js (fetch)"
const resp = await fetch(
  "https://api.ibee.ai/v1/object-storage/buckets?workspace_id=907479",
  { headers: { Authorization: "Bearer ibee_prod_key_xxxxxxxxxxxx" } }
);
const buckets = await resp.json();
```

> Official SDKs for the IBEE Solutions API.