Skip to navigation

API overview

The IBEE API is a REST API that lets you create and manage IBEE resources (virtual machines, storage, networks, secrets and more) from your own code, scripts or automation tools. You send an HTTPS request to https://api.ibee.ai/v1, prove who you are with an API token, and get a JSON answer back.

When to use the API

The API, the SDKs, the CLI and Terraform all reach the same IBEE resources. Pick the one that fits how you work:

You want to…Use
Do a one-off task by clickingThe portal
Call IBEE from any language, or with curl, without installing anythingThe HTTP API (this page)
Call IBEE from a Python or TypeScript programThe SDKs
Run commands in a terminal or a shell scriptThe CLI
Keep your infrastructure in files and review every change before it is madeTerraform

The active API covers Secret Manager, Cloud VMs, GPU VMs, the compute catalog, VPCs, Reserved IPs, firewalls, load balancers, Block Storage, CDN, and the organization’s wallet balance and top-ups (180 operations). Bare Metal Servers, SSH keys, ISOs, Virtual IPs, Email Service, DNS, SSL certificates, your account and team, and the rest of billing are managed in the portal only.

The SDKs and CLI keep their methods and commands for the paused operations, so existing code still builds. Those calls get the same 404 until management resumes.

How it works

  1. You create an API token in the portal. It is a secret string that says which organization you belong to, which products you may use and which workspaces you may touch.
  2. You send a request to https://api.ibee.ai/v1/... with the token in the Authorization header and the workspace’s ID in the workspace_id query parameter.
  3. The API gateway checks the request before anything happens: the token is valid and not revoked or expired, it has the right permission (scope), it may use that workspace, your organization is in good standing, and, for anything that costs money, Billing agrees. If a check fails you get an error code and nothing is done.
  4. The product service does the work and answers with JSON.

Before you begin

You need:

  • An IBEE organization with identity verification complete. Until it is, the portal shows Verify Identity instead of Create API Token. See Verify your identity.
  • To be an organization owner or administrator, or to ask one to create the token for you. Only they can open Organization → API Tokens.
  • The ID of the workspace you want to work in (step 2 below shows where to find it).
  • curl, which comes with macOS, Linux and Windows 10 or later.

Make your first call

This call lists the locations where you can create VMs. It only reads data: nothing is created and nothing is billed.

1

Create an API token

In the portal, open Organization → API Tokens in the sidebar and click Create API Token. Enter a Name, leave Access policy on Entire Organization, and under Permissions select Read on the Virtual Machines row. Under Token expiration, pick 7 days, 30 days, 90 days, 1 year or No expiration. Click Create API Token.

The API Token Created dialog shows the Bearer token once. Copy it now: it will not be shown again. Authentication explains every option.

2

Find your workspace ID

Open the workspace in the portal and look at the address bar. The number after /workspaces/ is the workspace ID:

https://portal.ibee.ai/organizations/ORG_ID/workspaces/907479/dashboard
^^^^^^ workspace ID

The Specific Workspaces list in the token dialog also shows each workspace’s ID next to its name.

3

Save both in your terminal

Replace the two values with your own. Keeping the token in an environment variable keeps it out of your shell history and your scripts.

export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx"
export IBEE_WORKSPACE_ID="907479"
4

Send the request

curl "https://api.ibee.ai/v1/compute/sites?workspace_id=$IBEE_WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_TOKEN"
5

Check the answer

A working call answers 200 OK with a list of sites and a count. The values depend on your account; the shape looks like this:

{
"sites": [
{ "site_id": "68b99bd78a8eda32ff3f16ea", "site_code": "…", "name": "…", "location": "…" }
],
"count": 1
}

If you get an error code instead, find it in Troubleshooting below.

Base URL and environments

EnvironmentBase URLToken starts with
Productionhttps://api.ibee.ai/v1ibee_prod_key_
Developmenthttps://api.ibee.co.in/v1ibee_dev_key_

A token works only on the environment that issued it. Every path in the reference is relative to the base URL, so GET /compute/sites means GET https://api.ibee.ai/v1/compute/sites.

Requests

Every request needs:

PartValue
Authorization headerBearer YOUR_API_TOKEN
workspace_id query parameterThe workspace to act in: a positive whole number such as 907479, given once. Without it the gateway answers 400 workspace_id_required.
Content-Type: application/json headerWhen the request has a body. Bodies are JSON.
X-Idempotency-Key headerA unique string per action, so a repeated request can be recognised. Required on the 18 VM writes and optional on the six networking creates described under Idempotency.

A workspace keeps resources apart, for example production, staging and development. A token can be limited to some workspaces when you create it.

The body of a request that creates something billable can be at most 65,536 bytes (64 KiB); a larger one is refused with 413 request_body_too_large. Keep other request bodies within the same limit: a much larger body can be refused before it is checked.

Responses

Successful responses usually contain JSON. Some gateway errors can be empty, HTML or plain text, as described below. Success codes:

StatusMeaning
200 OKThe read or change is done; the body is the result.
201 CreatedThe resource was created; the body is the new resource.
202 AcceptedThe work has started and will finish later. The body carries an ID to follow. See Asynchronous operations.
204 No ContentDone, with no body.

Lists have different shapes and page sizes per resource. See Lists and paging.

Errors

Most errors include a machine-readable error, a human-readable message and a correlation request_id, while preserving actionable product detail. Internal host addresses, device paths and diagnostic traces stay in service logs. Errors from the gateway’s authorization check can omit message or request_id and carry the fields below when relevant. When the gateway refuses a request, the request never reaches the product service, so nothing was created or changed.

{
"error": "insufficient_scope",
"required_scope": "vm.write",
"billing_reason": null,
"billing_sku_code": null,
"billing_evaluated_at": null,
"admission_context_id": null
}

Product detail remains available as a message, object or field-validation list, alongside the common fields:

{ "error": "validation_error", "message": "The request is invalid", "request_id": "req_example", "detail": "..." }

Branch your code on the HTTP status and the error code, never on message text.

Statuserror codes from the gatewayWhat to do
400workspace_id_required, invalid_workspace_id; on billable creates also invalid_json_body and selection codes such as plan_id_required, invalid_site_id or compute_billing_term_requiredFix the request. A 400 with detail comes from the product service.
401invalid_api_key: the token is missing, malformed or unknownCheck the Authorization header and the environment.
402billing_denied: Billing refused a billable create. billing_reason says why (see Billing refusals). Nothing is provisioned.Add credit or raise the limit, then retry.
403insufficient_scope (with required_scope), key_revoked, key_disabled, key_inactive, key_expired, unknown_route, workspace_not_allowed, principal_inactive, principal_not_member, principal_permission_denied, product_not_enabled; on writes also organization_restricted and verification_requiredSee Troubleshooting.
404With detail: the resource doesn’t exist in this workspace. With an empty body: a route is paused or unknown; this does not prove a resource was deleted. Terraform provider 0.8.0 and later keep state on this answer. Provider 0.7.0 and earlier remove the resource from state, so upgrade before you run plan or apply.Check the ID and the workspace_id, or the URL.
409(product service) The request conflicts with the resource’s current state. message gives the product’s reason where it’s safe to show. A networking create with a retry key can also answer idempotency_in_progress or idempotency_conflict; see Idempotency.Read the resource; if an operation is still running, wait for it to finish, then retry.
413request_body_too_large: a billable create’s body is over 64 KiB. A much larger body on any request can get a plain-text Payload Too Large.Send a smaller body.
422(product service) A parameter or the body failed validation; detail lists the fieldsFix the listed fields.
423organization_suspended: writes are refused while the organization is suspendedRetrying won’t help until the suspension is lifted. Contact support.
429A rate or concurrency limit was reachedWait and retry. See Rate limits.
500The service could not complete the requestKeep its request_id for investigation.
502bad_gateway: a service behind the gateway failed or sent an answer that couldn’t be used. It can also arrive from Cloudflare as HTML or plain text.Retry reads. Before you repeat a write, check whether it took effect, or retry a networking create with the same key and body.
503A required service is unavailable, for example workspace_verification_unavailable, product_check_unavailable or billing_admission_unavailableUse bounded read retries. Follow the operation’s idempotency rules for writes.
504A gateway or upstream timed outCheck a known operation, or recover a keyed create with the identical body and original key.

Cloudflare can return a problem-details object, HTML or plain text before the request reaches the API. Preserve the HTTP status and raw body when the normal JSON envelope is unavailable. Keep request_id (also returned as X-Request-Id) when contacting support.

Verified API-key write refusals can appear in Activity Logs. Activity delivery is best effort; the HTTP response is the immediate outcome.

Each endpoint in the reference lists the statuses it can return.

Billing refusals

There is no billing pre-check to call. Every billable create is checked by the gateway before it reaches a product service. A refusal answers 402 with error: billing_denied and a billing_reason:

billing_reasonWhat it usually means
initial_topup_requiredThe organization has not made its first top-up (at least ₹500, or $5 in USD) and has not received promo credit of at least ₹500. The message reads Add at least ₹500 to your wallet (Billing → Purchase credits in the portal) before creating resources.
insufficient_balanceThe balance is too low for this resource.
credit_limit_exceededThe organization’s credit limit would be exceeded.
resource_limit_reachedA plan limit on the number of resources was reached.
resource_usage_unavailableBilling could not count current usage. Retry later.
payment_verification_requiredObject Storage only: an organization billed in India hasn’t verified a payment method. Pay ₹1 in the portal; see Verify a payment method.
access_keys_require_topupObject Storage only: the organization is verified by the ₹1 alone, and S3 credentials need a top-up of at least ₹500.
free_storage_limit_reachedObject Storage only: the organization is verified by the ₹1 alone and already stores 25 GB. Top up, or delete files.

billing_sku_code names the product that was priced, and admission_context_id identifies the decision if you contact support. Add credit or raise the limit in the portal, then retry the same request. Send the published catalog selection; Billing calculates balances and charges server-side.

Idempotency

An idempotency key is a unique string you attach to a write so the server can recognise the same request if you send it again. These 18 VM writes require one in the X-Idempotency-Key header, for both /compute/cloud-vms and /compute/gpu-vms:

  • create (POST …) and delete (DELETE …/{vm_id});
  • start, stop and reboot (POST …/{vm_id}/actions/start, /stop, /reboot);
  • resize (POST …/actions/resize), access (PATCH …/actions/access), attach-volume and detach-volume (POST …/actions/attach-volume, /detach-volume).

Use a new key, such as a UUID, for each new action. Six networking creates also accept X-Idempotency-Key: VPC, subnet, NAT gateway, port forward, Reserved IP and firewall group. Their key is 1–256 visible ASCII characters and scoped to organization, workspace and path. See Retry a networking create. Container Registry’s plan upgrade takes its key in an Idempotency-Key header instead, and Block Storage create and resize take an optional idempotency_key field in the body.

curl -X POST "https://api.ibee.ai/v1/compute/cloud-vms/VM_ID/actions/reboot?workspace_id=$IBEE_WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_TOKEN" \
-H "X-Idempotency-Key: $(uuidgen)"

The answer is 202 Accepted with an operation_id to follow.

Poll a known operation_id. If a VM create response was lost, recover it by repeating the identical body with the original X-Idempotency-Key. Keep that body and key while the outcome is uncertain; a new key starts a separate create. Correct an explicit admission refusal, such as 402 billing_denied, before retrying.

Retry a networking create

Send the same key and the same body on every retry. What you get depends on what happened to the first request:

What happenedWhat the retry gets
The create completedThe original answer for 24 hours, even if the plan limit has since been reached.
It was refused or never sentNothing was created, so the key is free to use again, including with a corrected body.
The outcome is unknown (timeout, server error, lost connection)409 idempotency_in_progress with Retry-After. This usually lasts 30 seconds and at most 3 minutes. Keep retrying with the same key and body. The next retry returns the Reserved IP, subnet or NAT gateway. For a VPC, firewall group or port forward, it either creates the resource or answers 409 “already exists”.
The body changed, while the outcome is unresolved or after the create completed409 idempotency_conflict.

A new key at the plan limit gets 402.

VM create and delete

A site-filtered GET /compute/plans checks placement availability by default. selectable describes whether a plan has a usable price; available, availability, max_creatable and availability_reason describe advisory stock. Set include_availability=false for pricing-only discovery. An available result does not reserve capacity, and an absent plan is a catalog result rather than a stock count.

VM create takes site_id from GET /compute/sites, a plan_id and the plan’s billing_catalog from GET /compute/plans with the complete chosen billing_options entry merged in, and a template_id from GET /compute/images. Optional network fields (vpc_id with subnet_id, network_connectivity, vpc_attachment_mode, reserved_public_ip_id) launch it into a VPC; omit them to use the public network. See Create a cloud VM.

VM delete takes an optional body. A VM whose public IP was assigned automatically is refused with 400 unless you set public_ip_action: release gives the address up with the VM, and reserve keeps it as a Reserved IP.

public_ip_action applies only to an automatically assigned IP. If the VM’s IP is already a Reserved IP, send no body: release and reserve are both refused with 400. The IP stays in your workspace and keeps billing until you release it.

curl -X DELETE "https://api.ibee.ai/v1/compute/cloud-vms/VM_ID?workspace_id=$IBEE_WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_TOKEN" \
-H "X-Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"public_ip_action":"release"}'

Machine-readable access

Everything in this reference is also available as data, for code generators and AI agents:

WhatWhere
OpenAPI 3.1 specification, complete (the same file at each address)openapi.yaml · openapi.json · /docs/openapi/ibee-cloud.yaml
API catalog (RFC 9727)/.well-known/api-catalog
Index of every docs page, one line each/docs/llms.txt
Full text of every docs page in one file/docs/llms-full.txt
Markdown of any pageappend .md to its URL, for example create-cloud-vm.md
MCP server for AI clients (Claude Code, Cursor and others)https://ibee.ai/docs/_mcp/server
claude mcp add --transport http ibee-docs https://ibee.ai/docs/_mcp/server

Troubleshooting

The most common problems with a first call, most frequent first:

You seeWhat it meansWhat to do
401 invalid_api_keyThe token is missing, mistyped, or from the other environment (an ibee_dev_key_ token sent to api.ibee.ai)Send Authorization: Bearer <token> with the whole token. Use the base URL that matches the token.
400 workspace_id_requiredThe URL has no workspace_idAdd ?workspace_id=YOUR_WORKSPACE_ID. Quote the URL in your shell so ? and & survive.
400 invalid_workspace_idworkspace_id is empty or appears twiceSend it once, as a positive whole number.
403 insufficient_scopeThe token lacks the permission named in required_scopeCreate a token with that permission. See scopes.
403 workspace_not_allowedThe token’s access policy doesn’t include this workspace, or the workspace doesn’t exist or was deletedCheck the workspace ID, or use a token for Entire Organization or for this workspace.
403 key_expired or key_revokedThe token has passed its expiry date or was revokedCreate a new token.
403 product_not_enabledThe product isn’t turned on for your organizationAsk support for access.
403 verification_requiredThe token’s user hasn’t finished identity verification; writes are refusedComplete verification in the portal.
403 unknown_routeThe gateway can’t match the method and path to a permissionCheck the path and method against the reference.
402 billing_deniedBilling refused a billable createSee Billing refusals.
423 organization_suspendedThe organization is suspended, so writes are refused; reads still workContact support.
404 with an empty bodyA route is paused or unknown, for example /v1 is missing. Object Storage and Container Registry management are temporarily pausedCheck the method and URL against the reference.

When you contact support, include the time of the request, the error code, and the x-request-id response header if the response has one.