The client API lives at https://layeronecloud.com/api/v1/. It does what the
portal does: list plans and images, deploy servers, power them, manage private
networks and the firewall, read bandwidth usage, and destroy them.
The full field-by-field reference is at /docs/api/. This page gets you from nothing to a running server.
1. Check the API is open on your account
The API is locked until hourly billing is unlocked on an active account. Add credit, save a card, or complete a deposit and it opens. See What has to be true before you can deploy.
2. Create a key
Go to Developer in the client portal, /client/developer/, and create a key. Choose a scope:
| Scope | What it can do |
|---|---|
| Read only | GET and HEAD. Cannot deploy, power, or destroy anything |
| Full | Everything, including deploy and destroy |
Set an expiry if the key is for something temporary. You can hold up to 25 active keys, so there is no reason to share one between two systems.
The key is shown once
Nothing stores the secret half, so it cannot be shown again or emailed to you. Copy it into your secret store now. If you lose it, revoke it and create another.
A key looks like l1_a1b2c3d4e5f60718_<43 more characters>.
3. Make a call
Put the key in an environment variable so it does not end up in your shell history or a committed file.
export L1_API_KEY="l1_..."
Either header works:
curl -sS https://layeronecloud.com/api/v1/account \
-H "Authorization: Bearer $L1_API_KEY"
curl -sS https://layeronecloud.com/api/v1/account \
-H "X-API-Key: $L1_API_KEY"
You get back your email, billing account id, status, credit balance, this month's API usage, and this month's transfer pool with each server's share.
4. Find a plan and an image
curl -sS https://layeronecloud.com/api/v1/plans \
-H "Authorization: Bearer $L1_API_KEY"
Image availability is per plan, because an image whose minimum disk exceeds the plan's disk is filtered out. Ask for the plan you actually intend to use:
curl -sS "https://layeronecloud.com/api/v1/images?plan=layerone-starter" \
-H "Authorization: Bearer $L1_API_KEY"
Do not hardcode slugs out of a document
The catalog is live, and image slugs in particular are set per install and
change as operating system releases come and go. GET /api/v1/plans and
GET /api/v1/images are the source of truth for what you can deploy right
now and what it costs. The slugs in the examples below are illustrative.
5. Deploy a server
curl -sS -X POST https://layeronecloud.com/api/v1/servers \
-H "Authorization: Bearer $L1_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"plan": "layerone-starter",
"image": "ubuntu-24-04",
"label": "web-01",
"hostname": "web-01.example.com"
}'
The 201 response carries the server object, the order_id, and:
{
"root_password": "generated-once-only",
"root_password_generated": true
}
root_password appears in exactly one response, ever
This is the only endpoint that returns it and the only time it is retrievable. No listing or detail endpoint will ever include it. Capture it from the create response or reset it later from the portal.
Send your own root_password in the request body if you would rather not handle
a generated one. It has to satisfy the same complexity rules the portal enforces.
Useful optional fields:
| Field | Default | Notes |
|---|---|---|
label |
generated | Display name in the portal |
hostname |
generated | Set on the server itself |
root_password |
generated | Yours, or one we make |
public_ipv4 |
true |
false deploys private-only |
private_network |
none | Numeric id of a private network to join |
private_ip |
auto | A specific address inside that network |
6. Wait for it
Deployment is queued, so the create response has status of pending and a
null ipv4_address. Poll the detail endpoint:
watch -n 10 'curl -sS https://layeronecloud.com/api/v1/servers/123 \
-H "Authorization: Bearer $L1_API_KEY" | jq ".server | {status, ipv4_address}"'
Poll until status is running. ipv4_address fills in for a public server;
a private-only server keeps it null and sets private_ipv4 instead.
7. Clean up
curl -sS -X DELETE https://layeronecloud.com/api/v1/servers/123 \
-H "Authorization: Bearer $L1_API_KEY"
Answers 202. Billing stops once the teardown completes. The disk is gone with
it.