Client API

Base URL

https://chat.b18.io/api/v2/

Format

JSON request and response bodies, UTF-8

Authentication

An API key in a header. Cookies and sessions are never accepted.

Included requests

5,000 a month, then $1.00 per 100,000 requests

Paths on this page are relative to the base URL, so GET /servers means GET https://chat.b18.io/api/v2/servers. The older /api/v1/ base is legacy: it serves the same endpoints but always acts on the key's first workspace. Use v2 for anything new.

The API opens once hourly billing is unlocked on an active account. Servers you deploy bill hourly from your credit balance, the same as servers deployed from the client area.

This page is the field-by-field reference. For a walkthrough and copy-paste recipes, see API quickstart, API recipes and Rate limits and the monthly allowance.

Send the key on every request, in either header:

Authorization: Bearer l1_a1b2c3d4e5f60718_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# or

X-API-Key: l1_a1b2c3d4e5f60718_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The secret half of a key is shown once, when you create it, and we keep only a one-way fingerprint of it. If you lose it, revoke the key and create another.

Permissions

A workspace keeps its own servers and networks apart from the rest of the organization. In the API a workspace is called a tenant: GET /tenants lists the ones the key can reach, and you name one with ?tenant=<id>, "tenant": <id> in a JSON body, or the X-Tenant-Id header.

Leave it off and the request acts on the first workspace the key can reach: the organization's original workspace when the key can reach it. A server in another workspace reads as 404.

Every authenticated request is refused until hourly billing is unlocked on the account: a usable saved card, positive credit, credit already bought up front, or a server that is already running. Until then the response is 402 payment_required.

Creating another server has a funding check of its own. Any positive credit balance makes the hourly order $0.00 due and queues it immediately. With a usable saved card and a balance at or below zero, LayerOne charges exactly one month of credit for the selected plan before queueing the server. A decline or unconfirmed payment returns 402 payment_required and no server is queued. Without a usable card, add credit or complete the one-month checkout in the client area first.

A suspended or closed account is 403 forbidden on every endpoint, including reads. Keys can still be created and revoked under Settings → API keys; they cannot call the API until the account is active and unlocked again.

Requests

120 per minute, per key

Deployments

100 new servers per hour, per account

Over either limit returns 429 with the error code rate_limited. The per-minute request limit sends a Retry-After header; wait that long and retry. The deploy limit does not, so back off for the rest of the hour rather than looking for the header.

Included

5,000 requests a month

Over the allowance

$1.00 per 100,000 requests, taken from your credit balance

Every authenticated request that is actually served counts, including 4xx responses from the endpoint (a 404 for a missing server still used the API). Failed authentication, CORS preflight, rate-limited requests, a locked or suspended account, and a read-only key attempting a write do not count. Current usage is on GET /account and on every authenticated response as X-Api-Quota-Limit, X-Api-Quota-Remaining and X-Api-Quota-Used.

{
  "error": {
    "code": "invalid_request",
    "message": "'root_password' must be at least 12 characters.",
    "details": { "field": "root_password" }
  }
}

curl -X POST https://chat.b18.io/api/v2/servers \
  -H "Authorization: Bearer $LAYERONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "layerone-4g",
    "image": "ubuntu-24-04",
    "label": "web-01",
    "hostname": "web-01.example.com",
    "root_password": "correct-horse-Battery9"
  }'

The plan and image slugs above are real but illustrative. Read them from GET /plans and GET /images?plan=<slug> rather than hardcoding them: the catalog is live, and image availability is per plan because an image whose minimum disk exceeds the plan's is filtered out.

A 201 means the deployment is queued, not finished. The response carries the server id and, once only, the root password:

{
  "server": {
    "id": 4192,
    "label": "web-01",
    "hostname": "web-01.example.com",
    "status": "provisioning",
    "ipv4_address": null,
    "private_ipv4": null,
    "private_networks": [],
    "location": "Tampa",
    "plan": "layerone-4g",
    "image": { "slug": "ubuntu-24-04", "name": "Ubuntu 24.04", "os_family": "debian" },
    "specs": { "cpu_cores": 2, "memory_mb": 4096, "disk_gb": 60, "bandwidth_tb": "3.00" },
    "login_username": "root",
    "billing": { "cadence": "hourly", "hourly_rate": "0.0109", "monthly_equivalent": "7.96" },
    "created_at": "2026-08-19T14:02:11.417Z",
    "provisioned_at": null,
    "destroyed_at": null
  },
  "root_password": "correct-horse-Battery9",
  "root_password_generated": false,
  "order_id": 88213,
  "message": "Deployment queued. Poll GET /api/v2/servers/{id} until status is 'running'. ipv4_address is set for public IPv4; private-only servers keep it null; private addresses are configured inside the server or by your DHCP server."
}

Funding

Deployments are billed hourly and draw down your credit balance. With any positive balance, the hourly order has $0.00 due and is queued immediately. With a usable saved card and a balance at or below zero, LayerOne first charges exactly one month of credit for the selected plan; only a successful payment queues the server. A decline returns 402 payment_required and no server is created. Without a usable saved card, add credit or complete a one-month checkout in the client area. Monthly and annual commitments are not available through the API because they need an interactive payment page.

action is one of start, stop, restart, shutdown. shutdown asks the operating system to power down cleanly; stop cuts the power. There is no pause, and billing does not stop while a server is shut down.

curl -X POST https://chat.b18.io/api/v2/servers/4192/actions \
  -H "Authorization: Bearer $LAYERONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "restart"}'

Returns 202 with the queued action. Repeating a request that is already queued returns the same action rather than queueing a second one. A server that is still provisioning, already running a job, or suspended for billing returns 409 conflict with the reason in the message.

The network firewall in front of one deployed server, applied outside the server itself. It has the same rules as the client area: inbound and outbound default policy, then ordered allow, drop and reject rules. Anti-spoofing filters are managed by the platform and are not part of this API.

When firewall groups are assigned, GET returns the combined policy and rules, managed_by_groups: true, and a groups list with each group's id and name. Rules identify their source with group_id and group_name. Individual policy and rule writes return 409 until every group is removed. Manage assignments under Networking → Firewall groups in the client area.

curl https://chat.b18.io/api/v2/servers/4192/firewall \
  -H "Authorization: Bearer $LAYERONE_API_KEY"

curl -X PUT https://chat.b18.io/api/v2/servers/4192/firewall \
  -H "Authorization: Bearer $LAYERONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_policy": "DROP", "outbound_policy": "ACCEPT", "confirm_ssh_lockout": true}'

curl -X POST https://chat.b18.io/api/v2/servers/4192/firewall/rules \
  -H "Authorization: Bearer $LAYERONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direction": "in", "action": "ACCEPT", "protocol": "tcp", "port": "22"}'

inbound_policy and outbound_policy are ACCEPT or DROP. Switching inbound to DROP without a rule that allows TCP 22 requires confirm_ssh_lockout: true. The firewall cannot be turned off, and the platform's IP filter sets cannot be read or written.

Isolated networks on private (RFC 1918) address ranges, the same ones you manage under Networking → Private networks in the client area. The same limits apply: ten networks per account by default, sizes from /29 to /24, one attachment per server per network, and the last network on a private-only server cannot be detached. The platform keeps networks isolated from each other.

curl -X POST https://chat.b18.io/api/v2/networks \
  -H "Authorization: Bearer $LAYERONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "office", "cidr": "10.20.0.0/24"}'

curl -X POST https://chat.b18.io/api/v2/servers/4192/networks \
  -H "Authorization: Bearer $LAYERONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network": 12}'

PATCH accepts name, cidr (alias network_cidr) and gateway (an optional reference only; empty or null clears it). The retired cloud_init_assign_ips field only accepts false. Changing the range does not rewrite member addresses; they still have to fit. The server object lists every attachment as private_networks[]. A deploy can still join one existing network with private_network, without an address, on POST /servers.

Transfer is pooled per account, not capped per server. Server-level figures are attribution: they answer which server used the pool. They are not a per-server allowance. Each deployed server earns up to 500 GB (extra_per_additional_server_gb) per UTC calendar month, prorated by the time it has been deployed, on top of the 2 TB base. specs.bandwidth_tb on a server object is the plan's published figure, not this month's usage and not a cap.

instance_earned_tb and extra_server_allowance_tb report the same credits earned so far. allowance_tb includes only earned credits, the free base, and purchased blocks. potential_allowance_tb projects the pool at month end if your current servers stay deployed; future credits cannot be used yet. Stopped and suspended servers keep earning. A destroy request stops new credits, while earned transfer stays until the monthly reset.

Inbound and outbound are the server's totals across every interface, public and private, for the UTC calendar month. Traffic between two servers on a private network still counts. Figures update every few minutes; a server that has not been measured yet returns zeros for the current month rather than 404.

curl https://chat.b18.io/api/v2/servers/4192/bandwidth \
  -H "Authorization: Bearer $LAYERONE_API_KEY"

{
  "bandwidth": {
    "server_id": 4192,
    "label": "web-01",
    "current": {
      "period_start": "2026-08-01",
      "period_end": "2026-08-31",
      "used_bytes": 1234567890,
      "used_tb": "0.0012",
      "inbound_bytes": 800000000,
      "outbound_bytes": 434567890,
      "updated_at": "2026-08-16T12:00:00Z"
    },
    "periods": [ { "...": "current month first, then older months" } ],
    "account_pool": {
      "used_tb": "0.0012",
      "allowance_tb": "2.2500",
      "base_allowance_tb": "2.0000",
      "extra_server_allowance_tb": "0.2500",
      "extra_server_count": 1,
      "extra_per_additional_server_gb": 500,
      "instance_earned_tb": "0.2500",
      "instance_potential_tb": "0.5000",
      "instance_remaining_tb": "0.2500",
      "potential_allowance_tb": "2.5000",
      "reset_at": "2026-09-01T00:00:00+00:00",
      "remaining_tb": "2.2488",
      "overage_tb": "0.0000",
      "is_over": false
    }
  }
}

For every server in one request, read bandwidth.servers on GET /account instead of polling each server. That list is this month only; history lives on the per-server endpoint. Walkthrough: Bandwidth: pool, blocks, and overage.

curl -X DELETE https://chat.b18.io/api/v2/servers/4192 \
  -H "Authorization: Bearer $LAYERONE_API_KEY"

import json, os, time, urllib.request

BASE = "https://chat.b18.io/api/v2/"
KEY = os.environ["LAYERONE_API_KEY"]


def call(method, path, body=None):
    request = urllib.request.Request(
        BASE + path,
        method=method,
        data=json.dumps(body).encode() if body else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(request) as response:
        return json.load(response)


created = call("POST", "servers", {
    "plan": "layerone-4g",
    "image": "ubuntu-24-04",
    "label": "web-01",
    "root_password": os.environ["SERVER_ROOT_PASSWORD"],
})
server_id = created["server"]["id"]
print("queued", server_id)

# The address is assigned during provisioning, so poll for it.
for _ in range(60):
    server = call("GET", f"servers/{server_id}")["server"]
    if server["status"] == "running" and server["ipv4_address"]:
        print("ready:", server["ipv4_address"])
        break
    if server["status"] == "failed":
        raise SystemExit("provisioning failed")
    time.sleep(10)

# When you are finished with it:
# call("DELETE", f"servers/{server_id}")