Skip to content

One call first, then everything else

The next section shows a single request to ENTRONYX CLOUD and its response, explained field by field. Reading is enough; you can try out the call as soon as the API is published. This is followed by the command line and Terraform as a draft and the model behind it.

The index search runs entirely in your browser: no input leaves this page and no request is made to a search service.

Interface key facts

Articles in the index
49
in ten areas
API version
v2
planned, OpenAPI 3.1 as description
Deprecation period
12 months
planned, continued operation until the end
Rate limit
3,000/min
planned, per project and token

One question, one answer

The interface is an HTTP API: You send an address with a token — an access key that identifies you — and receive JSON in return, a text format that humans can read and programs can parse. The following call changes nothing. It only queries what is currently running. The interface is in preparation: The examples show paths, headers and responses as they are documented — the base path will be announced upon release.

The requestbash
# A token is in the environment, a project ID is known from the console.
# Draft of the future API: the base path will be stated with the release.
$ export ENTRONYX_TOKEN="ex_live_9f3c1a7d2b48e05c"
 
# Question: Which instances are running in the project, location Frankfurt?
$ curl -sS https://<Base-URL>/v2/compute/instances \
    -H "Authorization: Bearer $ENTRONYX_TOKEN" \
    -H "X-Entronyx-Project: prj_4c81f0" \
    -G --data-urlencode "region=fra1"
Two headers carry everything necessary: the token identifies you, the project ID tells in which area to search. -G appends the search conditions to the address instead of writing them in the body.
The responsejson
HTTP/2 200
content-type: application/json; charset=utf-8
x-request-id: req_8d41c0e7
x-ratelimit-remaining: 2999
 
{
  "data": [
    {
      "id": "inst_9a2f31",
      "name": "web-01",
      "state": "running",
      "flavor": "nx-4-8",
      "region": "fra1",
      "created_at": "2026-08-14T09:12:44Z",
      "network": {
        "ipv4": "185.42.7.19",
        "ipv6": "2a0e:97c0:3f0::19"
      }
    }
  ],
  "meta": {
    "total": 1,
    "next_cursor": null
  }
}
The status 200 stands for “found and delivered”. An empty list of results is also 200 — not 404. A 404 would mean: this address does not exist.

What comes back, field by field

data
The result list. It is always called data and is always a list, even with exactly one result. Your program therefore does not need a case distinction.
id
The resource identifier. It never changes and belongs in every fault report — an instance cannot be assigned by name alone.
state
The operating state: running, stopped, building or error. For building, the correct reaction is to query again, not to create again.
meta.next_cursor
If there is a value here, there are more pages; then append it as a cursor to the next query. If null, that was all.
x-request-id
The identifier of this single call, from the response header. Mention it in the ticket, then support will find exactly this request in the log.
x-ratelimit-remaining
How many calls are still free in the current minute. At 0, the interface responds with 429 instead of data.
Terminal window with a running call, next to a notepad with a handwritten project ID.
The call needs no library and no installation: curl is already available on every Linux and macOS. Up to 3,000 calls per minute and project are free — the three headers above are all that ENTRONYX CLOUD needs from you.

Three routes to the same interface

The same operation as above, but writing — and in three formats that are meant to talk to the same interface: the raw HTTP API, the command line and the Terraform provider. Terraform is a tool that builds infrastructure from text files; the provider is the module that teaches it ENTRONYX CLOUD. The command line and provider are in preparation; the examples show the intended structure. All calls go to version v2 of the interface. We announce the retirement of older versions twelve months in advance and continue to operate them during this time.

Base URL
will be announced upon release
Authentication
Bearer token
Rate limit
3,000 / min
Format
JSON, UTF-8

HTTP API with curl

Create an instancebash
# Create an instance. The response carries 201 and the new resource ID.
# Draft of the future API: the base path will be stated with the release.
$ curl -sS -X POST https://<Base-URL>/v2/compute/instances \
    -H "Authorization: Bearer $ENTRONYX_TOKEN" \
    -H "X-Entronyx-Project: prj_4c81f0" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 6f2a-web01-20260828" \
    -d '{
      "name": "web-01",
      "flavor": "nx-4-8",
      "region": "fra1",
      "image": "debian-13",
      "ssh_keys": ["key_7a21bc"],
      "private_network": "vnet_2f19",
      "backup_retention_days": 14
    }'
The Idempotency-Key header is optional, but highly recommended. It is a self-chosen identifier for exactly this one process: if the connection drops and you repeat the call, the interface recognises it and does not create a second instance. The key is valid for 24 hours.

Command line entronyx

Typical calls — draftbash
# Draft of the future command line. Package sources and installation commands will follow with the release.
 
# Log in and set the active project
$ entronyx auth login --token-file ~/.config/entronyx/token
$ entronyx config set-project prj_4c81f0
 
# Create instance and output only the IPv4 address
$ entronyx compute create \
    --name web-01 --flavor nx-4-8 --region fra1 \
    --image debian-13 --ssh-key key_7a21bc \
    --output json --query ".network.ipv4"
 
# Set node group of a Kubernetes cluster to six nodes
$ entronyx k8s nodepool scale --cluster k8s-prod --pool general --count 6 --wait
 
# List all servers in a region that are older than 400 days
$ entronyx bare-metal list --region dus1 --older-than 400d --output table
The command line is in preparation; package repositories and installation commands will follow with the release. A statically linked binary is planned — a single program file without runtime dependencies — for Linux, macOS and Windows with a return value (exit code) of 0 on success, 2 on usage errors, 3 on API errors, 4 on timeout.

Terraform provider

Provider, state storage and three instances — drafthcl
terraform {
  required_version = ">= 1.9"
 
  required_providers {
    entronyx = {
      # Draft: the provider is in preparation; its release will state source and version.
      source  = "<Quelle>"
      version = "<Version>"
    }
  }
 
  # State in own Object Storage, with server-side lock.
  backend "s3" {
    bucket       = "tfstate-prod"
    key          = "infra/terraform.tfstate"
    endpoints    = { s3 = "<S3-Endpunkt Ihres Buckets>" }
    region       = "fra1"
    use_lockfile = true
 
    skip_credentials_validation = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
  }
}
 
provider "entronyx" {
  # Token comes from ENTRONYX_TOKEN, not from this file.
  project = "prj_4c81f0"
  region  = "fra1"
}
 
resource "entronyx_private_network" "core" {
  name     = "core"
  cidr     = "10.42.0.0/16"
  regions  = ["fra1", "dus1"]
}
 
resource "entronyx_compute_instance" "web" {
  count = 3
 
  name            = format("web-%02d", count.index + 1)
  flavor          = "nx-4-8"
  image           = "debian-13"
  region          = "fra1"
  ssh_keys        = [entronyx_ssh_key.deploy.id]
  private_network = entronyx_private_network.core.id
 
  backup {
    retention_days = 14
    window         = "02:00-04:00"
  }
 
  lifecycle {
    # A change of the image forces a rebuild — deliberately blocked here.
    prevent_destroy = true
  }
}
The provider is in preparation; the example shows the planned structure, its release will specify the source and version. The state file can be stored in our Object Storage. The lock, which keeps two simultaneous runs apart, uses conditional writes and does not need an additional database.
Opened 2U server chassis from diagonally above on the workbench: heatsink with copper base over the socket, populated and locked memory banks, fan wall, power supplies with IEC connector at the back, drive bays at the front.

Four levels, nothing more

The identifiers from the example above are not random characters. Each names a level, and the levels are nested. If you know these four, you can read any address of the interface.

  1. Level 1

    Account

    A billing unit

    The account holds the contract, billing address and payment method. It does not contain any technology itself.

  2. Level 2

    Project

    prj_4c81f0

    The boundary for rights, costs and rate limits. A token is valid for exactly one project; if you address two projects, you need two tokens.

  3. Level 3

    Region

    fra1, dus1, hel1

    The physical location. Data only flows between regions if you explicitly set it up — a resource never changes region by itself.

  4. Level 4

    Resource

    inst_9a2f31

    Instance, volume, network, cluster. Each has an immutable identifier, each can be read, modified and deleted individually.

Authentication: one token, one project

Every call carries a token in the header Authorization. A token is valid for exactly one project and for the permissions you grant it upon issuance — read, operate, bill or manage.

  • A token is only visible once. Upon issuance, never again after that. Lost means reissue, not look up.
  • A token never belongs in the repository. In the environment, in a secret store or in the file that your command line reads — never in a file that is versioned, i.e. shared with the source code.
  • 401 means token, 403 means permission. With 401, the token is missing or expired. With 403, it is valid but does not cover the requested operation.
Closed front panel of a server row with the embossed ENTRONYX CLOUD wordmark.
Console, command line and Terraform provider should go through the same door: there is no second, more convenient way around the permissions check at ENTRONYX CLOUD. What a token is not allowed to do, a click cannot do either.

What your client must be able to do

Every error response contains an object with a machine-readable code, a plain text message and a request identifier for enquiries — the x-request-id from the first call. Only retry the codes that are marked as retryable. For all others, the result will not change as long as the request remains the same.

Response codes every client should handle
CodeMeaningRetryableRecommended behaviour
400Request malformednoCorrect the request, evaluate the error object
401Token missing, expired or revokednoObtain a new token
403Token valid, permission missingnoCheck the scope of the token
409State conflict, e.g. name already takennoRead existing resource
422Semantically invalid, e.g. flavor not in regionnoChoose an alternative
429Rate limit reachedyesWait for Retry-After, then back off exponentially (double the pause per attempt)
500Unexpected error on our sideyesUp to 3 attempts with random jitter
503Temporarily unavailableyesObserve Retry-After
For 429 and 503, the wait time is in the Retry-After header. If you ignore it and request again immediately, the block is extended.

Ten areas, all searchable

Searches cover title, short description and path. Matches are highlighted in the text, the number of hits is announced, and the hit list can be fully navigated with the arrow keys. Every article bears the date of the last technical review, not just the last text change.

49 articles in 10 sections

Arrow keys move through the results, Enter opens an entry, Escape clears the search.

First steps

6 articles

From account to the first running system. Once you are through this, you can automate everything else via the API.

Bare Metal

5 articles

Dedicated hardware: provisioning, operating systems, recovery and handling hardware failures.

Cloud

5 articles

Instances, images, snapshots and scaling in the Public Cloud. Per-second billing from start.

Kubernetes

5 articles

Managed clusters: control plane, node groups, storage and load balancer connection.

Storage

5 articles

Object Storage, Block Storage, Backup and archive. Limits, consistency guarantees and billing.

Network

4 articles

Addresses, private networks, load balancing, DDoS filters and what the backbone guarantees.

API reference

6 articles

REST over HTTPS, JSON, bearer tokens. Versioned under /v2, deprecations with twelve months' notice.

CLI

4 articles

The command-line tool entronyx. A statically linked binary for Linux, macOS and Windows.

Terraform

4 articles

Official provider in the registry. State management, imports and specifics per resource.

Billing

5 articles

Invoice runs, cost centres, quotas and the question of how a price on the invoice is calculated.

Note: this index maps the structure of the documentation portal. The individual article pages under the specified paths are not part of this setup — the paths stand here as identifiers, not as links. Therefore, an entry opens its details in place, instead of leading to a page that does not exist.

What works in the console should also work via the API

Terraform provider and command line are in preparation; they should use the same interface as the console so that there is no feature that can only be clicked. Until release, this documentation describes the interface with examples; you can already create tokens in the console today.

Description
OpenAPI 3.1
Terraform, CLI
in preparation
Token
in the console
Idempotency key
Valid for 24 h