Using the Worldstream API
Quick answer
The Worldstream API is for scripts, CI, and AI agents, not for clicking around in a browser. Create a key in Portal under Developers → API, then authenticate every request with an X-API-Key header, not a bearer token, against https://api.worldstream.com. The API is rate limited to 200 requests per minute per IP address.
Worldstream also supports connecting AI assistants and agents to this API through MCP (Model Context Protocol), see Using Worldstream via MCP for setup and what's currently possible end to end.
What you need before you start
- A Worldstream account with access to Portal
- An API key, created from API under Developers
- A tool to make HTTPS requests:
curl, Postman, or your language's HTTP client
Creating an API key
Open API under Developers
In Portal, go to Developers → API and select the Keys tab.
Click Create Key
Fill in a Key Name, choose how long it should last under Expires In, and set the permissions the key needs.
Copy the secret immediately
Treat the secret as unrecoverable once you leave the screen. Store it somewhere safe straight away, such as a password manager or secrets store. Never paste an API secret into a support ticket.
The same Keys area also has an API IP allowlist, which restricts which addresses may authenticate using a key. It has three modes: Off, Report only, and Enforce. This only affects API key authentication, it has no effect on browser sign-in to Portal.
Authenticating
Send the key as an X-API-Key header on every request. It's not a bearer token, so don't put it in an Authorization: Bearer header.
curl -H "X-API-Key: <your-api-key>" \
https://api.worldstream.com/<family>/v1/<command>Endpoints are grouped by product family and follow the pattern api.worldstream.com/<family>/v1/<command>. Take the exact path for any call from the Endpoints tab in Portal, which is generated live from the same OpenAPI spec as Download Spec.
Rate limits
The API allows 200 requests per minute per IP address. Go over that and you'll get an HTTP 429 response with a Retry-After header telling you how long to wait before your next request. Build retry logic around that header rather than guessing an interval, particularly for scripts that poll on a schedule.
Finding endpoints and documentation
The API section in Portal scopes what you see to your own access:
- My APIs shows what your account and key can actually call.
- Full reference shows every available endpoint, regardless of your current access.
- Download Spec gets you the OpenAPI spec, for generating clients or wiring up tooling.
- View JSON and API Explorer let you inspect and try endpoints directly in the portal.
- Infrastructure as Code gives you ready-made Ansible and Terraform templates, built from the live spec.
- Examples includes an MCP Server Setup guide for connecting the API to Cursor or Claude Desktop, see Using Worldstream via MCP.
Calling an endpoint your account or key doesn't have access to returns an HTTP 403.
If a call returns a 403, check Recent API key denials on the Keys tab. It shows whether the denial was a permission issue or an IP restriction from the API IP allowlist.
Common tasks
Every endpoint follows the same pattern: https://api.worldstream.com/<family>/v1/<command>. The table below shows how that pattern maps onto typical tasks. Take the exact path for any call from the Endpoints tab, View JSON, or API Explorer in Portal rather than copying these as-is.
| Task | Illustrative endpoint pattern |
|---|---|
| List your Flexible VPS instances | GET /flexible-vps/v1/vms |
| Create a Flexible VPS | POST /flexible-vps/v1/vms |
| Power on/off/restart a VPS | POST /flexible-vps/v1/vms/{id}/actions |
| List dedicated servers | GET /dedicated/v1/dedicated-servers |
| Reinstall a dedicated server's OS | POST /dedicated/v1/dedicated-servers/{id}/reinstall |
| Set reverse DNS on an IP | PUT /ip-management/v1/dns/reverse-records/{id} |
| Create an Object Storage bucket | POST /storage/v1/object-storage/buckets |
| Open a support ticket | POST /support/v1/tickets |
| Estimate the cost of a configuration | POST /account/v1/pricing/estimate |
The API families and their sizes are: Account (27 endpoints), Flexible VPS (88), Kubernetes (27), Dedicated Servers (25), Storage (14), Datacenter (20), IP Management (8), Monitoring (9), and Support (6), 224 endpoints in total. Each family covers the tasks you'd expect from its name, for example Flexible VPS covers the full VM lifecycle (create, power, resize, redeploy, snapshots, backups, networks, firewalls, VPN, ISOs, images), and Dedicated Servers covers power, reinstall, cancel, traffic, and uplinks. See the Endpoints tab in Portal for the full, current list, grouped by family. Note what's not here: there is currently no endpoint for account signup or adding a payment method, invoicing and billing management still happen in Portal itself.