Account

Read your account

GET/v1/account/

Returns your user and account IDs, and every part of your account you can read: keys, invitations, billing, addresses and defaults.

Query

organization string

Act in this organization (its name or ID) instead of your personal account.

• An API key needs account view in its commands.

Change your email address

POST/v1/account/modify"action": "account email"

Changes the address you sign in with and Heaven writes to. Without code, it mails a code to the new address. With the code, it makes the change and tells the old address.

Body

email string required

The new address, such as ada@example.com.

code string

The code Heaven mailed to the new address. Treated as a secret and never included in errors.

old_code string

The code Heaven mailed to your current address. Treated as a secret and never included in errors.

• API keys you create can't run it. Use a sign-in key or SSH.

Set your name

POST/v1/account/modify"action": "account name"

Sets the name people see beside your email address. clear removes it.

Body

name string

Your name, as people should see it.

clear boolean

Remove your name.

• API keys you create can't run it. Use a sign-in key or SSH.

List the commands a key can run

GET/v1/account/?view=commands

Lists every command an API key can name, with its endpoint and fields, and whether you can give it to a key.

Each command comes with its route, fields, flags and usage, and says whether a key with a scope can run it.

Query

command string

Read only this command, in full, such as pool create.

full boolean

With false, list each command by its name, summary, endpoint and fields only. Defaults to true (MCP tools: false).

• Any API key can run it.

List SSH keys

GET/v1/account/?view=ssh-keys

Lists your active SSH keys.

• An API key needs ssh-key view in its commands.

Add an SSH key

POST/v1/account/modify"action": "ssh-key add"

Adds an SSH public key. You can limit it to the Computers with a tag, or to one Computer.

With tag, the key reaches only Computers that carry that tag. With computer, it reaches only that Computer, and you need ownership or root access on it. Either way, the key can't run commands.

Body

public_key string required

The public key, as in ~/.ssh/id_ed25519.pub.

label string

A label to recognize it by.

tag string

Let the key reach only Computers with this tag.

computer string

Let the key reach only this Computer.

• API keys you create can't run it. Use a sign-in key or SSH.

Make a site token

POST/v1/account/modify"action": "ssh-key create"

Makes a token a program can use to open one Computer's private site. A new SSH key limited to that Computer signs it, and the token works until you remove that key.

Body

computer string required

The Computer whose private site the token opens.

label string

A name for its key in ssh-key view, such as deploy.

• API keys you create can't run it. Use a sign-in key or SSH.

Rename an SSH key

POST/v1/account/modify"action": "ssh-key rename"

Changes an SSH key's label.

Body

key string required

The key: its ID or exact label.

label string required

The new label.

• An API key needs ssh-key rename in its commands.

Remove an SSH key

POST/v1/account/modify"action": "ssh-key remove"

Revokes an SSH key and every token signed with it.

Body

key string required

The key's ID (see ssh-key view).

• An API key needs ssh-key remove in its commands.

List API keys

GET/v1/account/?view=api-keys

Lists your API keys that still work, with their labels, expiry and last use. Their secrets are never shown.

Your sign-ins are listed with them, each with its label, commands, scope and expiry.

Query

all boolean

Include finished and canceled ones.

• An API key needs api-key view in its commands.

Create an API key

POST/v1/account/modify"action": "api-key create"

Creates a key that can run only the commands it names. You can also limit it to some pools, Computers and tags. The response shows its token once.

See what a key can run and what it can reach.

Body

label string

A label to recognize it by.

expires string required

How long the key works, such as 30d or 12h, up to 365d, or never.

commands string[]

A command the key can run. Without any, the key gets the read-only set.

scope object

Limit the key to these pools, Computers and Computers with these tags, up to 64 of each.

computers string[]

Limit the key to this Computer.

pools string[]

Limit the key to this pool's Computers.

tags string[]

Limit the key to Computers with this tag.

• An API key needs api-key create in its commands.

Remove an API key

POST/v1/account/modify"action": "api-key remove"

Revokes an API key at once.

It also ends a sign-in, given the sign-in's ID.

Body

key string required

The key's ID (see api-key view).

• An API key needs api-key remove in its commands.

Edit an API key

POST/v1/account/modify"action": "api-key edit"

Changes a key's label, commands, scope or expiry, and keeps its ID and secret. New commands or a new scope replace the old ones, no_scope removes the scope, and a new expiry counts from now.

Body

key string required

The key's ID (see api-key view).

label string

A label to recognize it by.

expires string

The key's new expiry, counted from now, such as 30d or 12h (up to 365d), or never.

commands string[]

A command the key can run, replacing its list.

no_scope boolean

Remove the key's scope, so it reaches everything its commands allow.

scope object

Limit the key to these pools, Computers and Computers with these tags, up to 64 of each.

computers string[]

Limit the key to this Computer.

pools string[]

Limit the key to this pool's Computers.

tags string[]

Limit the key to Computers with this tag.

• API keys you create can't run it. Use a sign-in key or SSH.

Rotate an API key

POST/v1/account/modify"action": "api-key rotate"

Gives an API key a new secret, shown once, and keeps its ID, commands, scope and expiry. The old secret keeps working for overlap.

Body

key string required

The key's ID (see api-key view).

overlap string

How long the old secret keeps working: 0 to 7d (default 24h).

• An API key needs api-key rotate in its commands.

Read billing

GET/v1/account/?view=billing

Returns what needs attention, the next renewal, what each purchase costs, the wallet and how long it will last, automatic top-up, recent charges and this month's egress.

Query

organization string

Act in this organization (its name or ID) instead of your personal account.

• An API key needs billing view in its commands.

List charges

GET/v1/account/?view=charges

Lists every top-up, credit and charge on your account, newest first, one page at a time.

Query

before string

The next value from the previous page, or an RFC 3339 time, to read older entries.

limit string

How many entries to return: 50 by default, up to 500.

organization string

Act in this organization (its name or ID) instead of your personal account.

• An API key needs billing history in its commands.

List invoices

GET/v1/account/?view=invoices

Lists every invoice, for monthly plans, prorations and top-ups, newest first, each with its Stripe page.

Query

organization string

Act in this organization (its name or ID) instead of your personal account.

• An API key needs billing invoices in its commands.

Top up the wallet

POST/v1/account/modify"action": "billing top-up"

Returns a Stripe page where you add $5 to $1,000 to your wallet, and get an invoice for it.

In an account's first 30 days, each top-up is at most $250. The first top-up saves the card and turns on automatic top-ups of $20, unless you send no_auto_top_up.

Body

amount string

The amount in whole dollars, from 5 to 1000.

auto_top_up string

With the first top-up, the amount of each automatic top-up, in whole dollars (default 20).

no_auto_top_up boolean

Don't save the card for automatic top-ups.

invoice boolean

Get a bank-transfer invoice instead of Stripe's card page. Only for accounts approved for it.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Charge your saved card

POST/v1/account/modify"action": "billing charge"

Adds $5 to $1,000 to your wallet from your saved card, at once.

If the card needs you to confirm the payment, the request returns payment_required with Stripe's page in url. If the response is unknown, Heaven settles the charge with Stripe within minutes and never makes it twice. To find out what happened, send the same Idempotency-Key again, or list your charges.

Body

amount string required

How much to add, whole dollars from 5 to 1000.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.
• A key whose commands allow it must also allow billing top-up.
• Retry it safely with an Idempotency-Key header.

Set automatic top-up

POST/v1/account/modify"action": "billing auto-top-up"

Tops up the wallet from your saved card when less than a day of use is left, up to a monthly limit, or turns this off.

It tops up at most 5 times a day.

Body

amount string

The amount in whole dollars, from 5 to 1000.

monthly_limit string

The most automatic top-ups can add in a month, in whole dollars: $500 unless you set it, up to $5,000.

off boolean

Turn it off.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.
• A key whose commands allow it must also allow billing top-up.

Refund the wallet

POST/v1/account/modify"action": "billing refund"

Refunds the wallet's unspent money from top-ups in the last 180 days to the cards it came from.

Heaven refunds the newest top-ups first. Promotional credit is never refunded. For money older than 180 days, contact support.

Body

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Pay an invoice

POST/v1/account/modify"action": "billing pay"

Pays an open invoice with your card. Without an invoice, it pays the failed renewal.

If the card needs you to confirm the payment, the response is Stripe's page for doing so.

Body

invoice string

An invoice's ID (see billing invoices).

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Redeem an offer

POST/v1/account/modify"action": "billing redeem"

Redeems an offer code. Credit goes into the wallet at once, and a discount, trial or boost applies to your next purchase it fits.

Credit is spent before money you paid. It's never refunded, and it can expire. A discount, trial or boost waits for the account's next purchase it fits, and its time starts then.

The request is refused, with the reason, if the offer is unknown, paused, ended or fully redeemed, if this account already redeemed it, or if it isn't for this account.

Body

code string required

The offer code.

organization string

Act in this organization (its name or ID) instead of your personal account.

• An API key needs billing redeem in its commands.

Read or set the egress cap

POST/v1/account/modify"action": "billing egress-cap"

Returns this month's egress and its spending cap, or sets, removes or resets the cap.

The response has this month's egress, the pooled allowance, projected use, the overage so far and what it cost, and the cap. While egress charging is switched off, it says what would be charged instead.

default sets the cap to what the account's plans cost for the month. At the cap, egress charges stop, and internet egress slows to 5 Mbit/s per pool until the month ends or you raise the cap. Only the account's owner, or an organization's billing owner and admins, can change it.

Body

amount string

The amount in whole dollars, from 5 to 1000.

off boolean

Turn it off.

default boolean

Go back to the default cap, which is what your plans cost for the month.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

List billing contacts

GET/v1/account/?view=billing-contacts

Lists the extra addresses that get invoices and billing emails.

Query

organization string

Act in this organization (its name or ID) instead of your personal account.

• An API key needs billing contacts in its commands.

Add a billing contact

POST/v1/account/modify"action": "billing contacts add"

Also sends invoices and billing emails to another address, such as your accounting team's.

Body

email string required

The address to add.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Remove a billing contact

POST/v1/account/modify"action": "billing contacts remove"

Stops sending billing emails to an extra address.

Body

email string required

The address to remove.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Set the billing time zone

POST/v1/account/modify"action": "billing time-zone"

Sets a time zone for deadlines in billing emails, shown beside UTC.

Body

zone string required

An IANA time zone, such as Europe/Berlin.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Turn usage notices on or off

POST/v1/account/modify"action": "billing usage-emails"

Turns usage notices, about egress nearing its allowance or cap, on or off.

Usage notices are sent when egress reaches 80% and 100% of the allowance, and 80% of the cap. Billing emails, about payments, the wallet and deletions, are always sent.

Body

on boolean

Send usage notices again.

off boolean

Stop usage notices. Billing emails are still sent.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Set invoice details

POST/v1/account/modify"action": "billing details"

Sets the email, company, tax ID and postal address on your invoices and receipts. With none of them, returns the current details.

Body

organization string

Act in this organization (its name or ID) instead of your personal account.

email string

The email invoices go to.

company string

The company name on invoices.

tax_id string

A tax ID as TYPE:NUMBER, such as eu_vat:DE123456789. Send "" to remove it.

postal_address object

The postal address on invoices. line1 and country are required.

line1 string required

The address's first line.

line2 string

The address's second line.

city string

The city.

state string

The state or region.

postal_code string

The postal code.

country string

The country, as a two-letter code (such as DE).

• API keys you create can't run it. Use a sign-in key or SSH.

Start saving a card

POST/v1/account/modify"action": "billing card setup"

Returns what Stripe's card fields need to take a card for your account with no payment: a setup, its client secret and Heaven's publishable key. The dashboard's Add card dialog uses it.

Body

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Save a card

POST/v1/account/modify"action": "billing card save"

Makes the card a setup saved your account's card, once Stripe has confirmed it: the one charges, automatic top-ups and monthly plans use.

Body

setup string required

The setup billing card setup answered (seti_…), once Stripe has confirmed its card.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Open the billing portal

POST/v1/account/modify"action": "billing portal"

Returns a link to Stripe's page for your card, billing address, tax IDs and invoices.

You change plans in Heaven, not in the portal.

Body

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Buy capacity

POST/v1/account/modify"action": "capacity buy"

Buys a plan's capacity on one server without making a pool. Pay monthly on your account's subscription, or by the hour from your wallet.

• Monthly (the default) adds a line to your account's subscription. Your first purchase returns a checkout_url: pay there by card within 30 minutes. Later purchases charge the prorated amount up to your renewal date, and return an invoice_url when the card needs you to confirm.
• Hourly is paid from your wallet by the minute, for at least an hour. The wallet must cover the first hour.

Body

plan string

The plan's number, 1 to 6 (see plan view).

monthly boolean

Pay monthly, on your account's subscription (the default).

hourly boolean

Pay by the minute from your wallet, for at least an hour.

offer string

An offer's code or ID.

dry_run boolean

Change nothing, and show what it would do and charge.

server string

The server to buy on. Defaults to the one with the most room.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.
• Retry it safely with an Idempotency-Key header.

Change a purchase's plan

POST/v1/account/modify"action": "capacity resize"

Moves a purchase to another plan. A monthly upgrade applies once the prorated difference is paid, and a downgrade at the end of the period. An hourly purchase changes at once.

dry_run returns Stripe's preview of the prorated difference and changes nothing.

Body

capacity string required

The purchase's ID (see capacity view).

plan string

The plan's number, 1 to 6 (see plan view).

dry_run boolean

Change nothing, and show what it would do and charge.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Switch monthly or hourly

POST/v1/account/modify"action": "capacity switch"

Switches a purchase to monthly as soon as the first month is paid, or to hourly at the end of the paid period.

Until the first month is paid, you pay the hourly rate. No hour is paid twice.

Body

capacity string required

The purchase's ID (see capacity view).

monthly boolean

Switch to monthly once the first month is paid.

hourly boolean

Switch to hourly at the end of the paid period.

dry_run boolean

Change nothing, and show what it would do and charge.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Cancel a scheduled change

POST/v1/account/modify"action": "capacity cancel-change"

Cancels a purchase's scheduled downgrade, release or switch to hourly. The purchase keeps its plan and renews as before.

Body

capacity string required

The purchase's ID (see capacity view).

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

Release capacity

POST/v1/account/modify"action": "capacity release"

Ends a purchase. Hourly capacity ends at once, and a monthly plan at the end of the period paid for.

If the purchase is already released, the response has its released_at.

• Hourly: you pay for at least its first hour.
• Monthly: it ends at releases_at, and you can use it until then. capacity cancel-change undoes the release. If you release your first monthly purchase within 48 hours, it ends at once and is refunded. This applies once.

You can't release capacity while pools on its server still need its memory. You also can't release it while your pools there, stopped ones included, store more than 120% of the storage that would be left. The error names the pools and what each stores.

Body

capacity string required

The purchase's ID (see capacity view).

yes boolean

Confirm. Without it nothing changes, and the response says what would happen.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.

List static addresses

GET/v1/account/?view=addresses

Lists your account's static IPv4 addresses, what each is attached to, and your limit.

Query

organization string

Act in this organization (its name or ID) instead of your personal account.

• An API key needs ip view in its commands.
• Not available yet: it returns unavailable until static addresses are offered.

Buy static addresses

POST/v1/account/modify"action": "ip buy"

Buys static IPv4 addresses for your account, or takes back one you released in the last 7 days.

Heaven buys all count addresses or none.

Body

region string

Where the address is routed (default the only one).

count string

How many to buy (default 1).

address string

An address you released in the last 7 days, to take back.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.
• Retry it safely with an Idempotency-Key header.
• Not available yet: it returns unavailable until static addresses are offered.

Attach static addresses

POST/v1/account/modify"action": "ip attach"

Attaches a static address to a Computer, a pool, or your account on one server.

Attaching moves the address off anything it was attached to. To attach several at once, use attachments.

Body

address string

The address to attach.

computer string

The Computer to attach it to.

pool string

Attach it to this pool instead.

account boolean

Attach it to your account on one server instead.

server string

With account: the server, when your pools are on several.

attachments object[]

Each address and what it attaches to: {address, computer}, {address, pool} or {address, account: true}.

account boolean

true attaches it to your account on one server.

address string required

The address to attach.

computer string

The Computer to attach it to.

pool string

The pool to attach it to.

server string

With account, the server, when your pools are on several servers.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.
• Also on /v1/pool/modify and /v1/computer/modify, for one pool or Computer.
• Not available yet: it returns unavailable until static addresses are offered.

Detach static addresses

POST/v1/account/modify"action": "ip detach"

Detaches static addresses from their Computer, pool or server. Your account keeps them.

With computer or pool, each address must be attached there, or the request is refused.

Body

addresses string[] required

Static IPv4 addresses of your account.

computer string

The Computer they must be attached to.

pool string

The pool they must be attached to.

organization string

Act in this organization (its name or ID) instead of your personal account.

• An API key needs ip detach in its commands.
• Also on /v1/pool/modify and /v1/computer/modify, for one pool or Computer.
• Not available yet: it returns unavailable until static addresses are offered.

Release static addresses

POST/v1/account/modify"action": "ip release"

Gives static addresses back to Heaven.

For 7 days no other account can get them, and you can take each one back with ip buy and its address.

Body

addresses string[] required

Static IPv4 addresses of your account.

yes boolean

Confirm. Without it nothing changes, and the response says what would happen.

organization string

Act in this organization (its name or ID) instead of your personal account.

• API keys you create can't run it. Use a sign-in key or SSH.
• Not available yet: it returns unavailable until static addresses are offered.

Read your default setup script

GET/v1/account/?view=defaults

Returns the setup script a new Computer runs when it's created without one.

• An API key needs defaults view in its commands.

Set your default setup script

POST/v1/account/modify"action": "defaults set"

Sets the setup script a new Computer runs when it's created without one.

The script can be up to 10 KiB. Heaven stores it encrypted.

Body

setup_script string required

The script. Treated as a secret and never included in errors.

• API keys you create can't run it. Use a sign-in key or SSH.

Clear your default setup script

POST/v1/account/modify"action": "defaults clear"

Removes your default setup script.

• API keys you create can't run it. Use a sign-in key or SSH.

Read your sign-in lifetime

GET/v1/account/?view=sign-in

Returns how long your sign-ins last, on this website and on private websites.

• An API key needs sign-in view in its commands.

Set your sign-in lifetime

POST/v1/account/modify"action": "sign-in lifetime"

Sets how long your sign-ins last: 7d, 14d, 28d, 90d (the default) or never.

Body

lifetime string required

How long sign-ins last: 7d, 14d, 28d, 90d or never.

• API keys you create can't run it. Use a sign-in key or SSH.

Sign out everywhere

POST/v1/account/modify"action": "sign-in end-all"

Ends every sign-in to this website, in every browser, and to private websites. SSH and API keys stay.

• API keys you create can't run it. Use a sign-in key or SSH.

List your invitations

GET/v1/account/?view=invitations

Lists invitations to you from organizations and teams.

• An API key needs invitation view in its commands.

Accept an invitation

POST/v1/account/modify"action": "invitation accept"

Joins the organization or team that invited you.

Body

invitation string required

The invitation's ID, the organization's name, or ORGANIZATION@TEAM for a team.

• API keys you create can't run it. Use a sign-in key or SSH.

Decline an invitation

POST/v1/account/modify"action": "invitation decline"

Declines an invitation to an organization or team.

Body

invitation string required

The invitation: its ID, the organization's name, or ORGANIZATION@TEAM.

• API keys you create can't run it. Use a sign-in key or SSH.

Delete your account

POST/v1/account/delete

Deletes your account in two steps. The first request emails you a code and returns what will be deleted. The second, with the code and yes, deletes it.

The code is 8 digits. It lasts 15 minutes or 5 tries, and Heaven sends at most one a minute.

The second step leaves your organizations, deletes your Computers, pools and capacity, and erases your identity. It returns an operation group. From then on your account is suspended: every other request is refused until deletion finishes, except reading that operation group.

The first step's balance_micros is your personal balance. Deleting your account forfeits it, since balances aren't refunded.

If you're the last member of an organization, it closes. If you're an organization's billing owner, your cards stop paying for it, and Heaven offers billing ownership to its first admin, or to its first member if it has no admins. Nobody becomes billing owner without accepting. Until someone does:

• the organization runs on its balance;
• its admins get its billing emails, or all its members if it has no admins;
• paying by card and buying monthly capacity are refused, until an admin offers billing ownership and a member accepts it.

Body

yes boolean

Confirm. Without it nothing changes, and the response says what would happen.

transfer_computers_to object

Who in each organization gets your Computers there. Without it, each organization keeps them.

user string required

A member of your organizations who gets your Computers there.

code string

The code the first request mailed you. Treated as a secret and never included in errors.

• API keys you create can't run it. Use a sign-in key or SSH.