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:
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
- 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.
- You send a request to
https://api.ibee.ai/v1/...with the token in theAuthorizationheader and the workspace’s ID in theworkspace_idquery parameter. - 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.
- 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.
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.
Find your workspace ID
Open the workspace in the portal and look at the address bar. The number after /workspaces/ is the workspace ID:
The Specific Workspaces list in the token dialog also shows each workspace’s ID next to its name.
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.
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:
If you get an error code instead, find it in Troubleshooting below.
Base URL and environments
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:
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:
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.
Product detail remains available as a message, object or field-validation list, alongside the common fields:
Branch your code on the HTTP status and the error code, never on message text.
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_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.
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:
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.
Machine-readable access
Everything in this reference is also available as data, for code generators and AI agents:
Troubleshooting
The most common problems with a first call, most frequent first:
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.
Related pages
- Authentication: create tokens, choose permissions, expiry and revoking
- Rate limits: what to do with
429and503 - Asynchronous operations: follow a
202to the end - Lists and paging: page sizes and shapes of every list
- SDKs, CLI and Terraform
- Examples: runnable code for every product
