# Public API Changelog All notable changes to this API will be documented here. The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). There are no versions at this time. Only date stamps. For the latest actual specification, please see `/openapi.json` and/or `/docs`. ## Major bugs - 2023-10-02 to 2024-09-02: Server topup attempts past one year that returned a HTTP 422 saying that server expirations can't go past one year would eat token funds without extending server expiration. Please see our [blog post](https://sporestack.com/blog/posts/2024-09-06-server-topup-bug.html) about the bug. The blog post is also available on our [Tor Hidden Service](http://spore64i5sofqlfz5gq2ju4msgzojjwifls7rok2cti624zyq3fcelad.onion/blog/posts/2024-09-06-server-topup-bug.html). ## Currently deprecated features These dates are when they are deprecated. You should make changes as soon as possible. There are no firm dates on when they will be removed. - POST /token/{token}/servers: You must start passing a provider for server launch calls. Currently, provider defaults to digitalocean, but this default will be removed. ## Recent breaking changes - If a server fails to autorenew due to insufficient funds (maintain 7+ days expiration), it will be powered off to signal that the token has run out. To turn through the remaining balance you have to disable autorenew on the server and then power it on. If you top up a token, you have to manually power on the server after if it's been stopped. - `/server/{machine_id}/forget` no longer deletes the server from the database. It now sets `forgotten_at` as a signal that the server is to be ignored by clients. Deleted servers, whether forgotten or not, will be removed from our database after 90 days. - Type of `id` in invoices changed from an integer to a string. - `GET /operatingsystems` removed in favor of `GET /slugs/os` - `GET /regions` removed in favor of `GET /slugs/regions` - `GET /flavors` removed in favor of `GET /slugs/flavors` - `token` removed from `GET /token/{token}/servers/{machine_id}`'s response as it was redundant. - 2024-11-11: `POST /server/{machine_id}/launch` was removed in favor of `POST /token/{token}/servers`. A `machine_id` will be returned for you. - 2025-01-24: `DELETE /server/{machine_id}` was removed in favor of `DELETE /token/{token}/servers/{machine_id}` - 2025-01-24: `POST /server/{machine_id}/forget` was removed in favor of `POST /token/{token}/servers/{machine_id}/forget` - 2025-03-28: `POST /server/{machine_id}/topup` was removed in favor of `POST /token/{token}/servers/{machine_id}/topup` - 2025-03-31: `POST /server/{machine_id}/autorenew/enable` was removed in favor of `PATCH /token/{token}/servers/{machine_id}` - 2025-03-31: `POST /server/{machine_id}/autorenew/disable` was removed in favor of `PATCH /token/{token}/servers/{machine_id}` - 2025-03-31: `POST /server/{machine_id}/rebuild` was removed in favor of `POST /token/{token}/servers/{machine_id}/rebuild` - 2025-03-31: `PATCH /server/{machine_id}` was removed in favor of `PATCH /token/{token}/servers/{machine_id}` - 2025-03-31: `POST /server/{machine_id}/start` was removed in favor of `POST /token/{token}/servers/{machine_id}/start` - 2025-03-31: `POST /server/{machine_id}/stop` was removed in favor of `POST /token/{token}/servers/{machine_id}/stop` - 2025-04-02: `GET /server/{machine_id}/info` deprecated in favor of `GET /token/{token}/servers/{machine_id}` - 2025-04-02: `token` entries per server were removed from `GET /token/{token}/servers` as they are redundant. - 2025-04-02: `flavor` dictionaries per server were removed from `GET /token/{token}/servers`. Use `flavor_slug` instead. ## Notices - If launching a server set to autorenew, it's no longer necessary to specify how many days it will live. #### Known issues with Vultr servers - Cannot allow SMTP on these servers, at this time. IRC may also be blocked. Vultr has a [public list of blocked ports](https://docs.vultr.com/what-ports-are-blocked). ## [2025-05-19] ### Deprecation notices - POST /token/{token}/servers: You must start passing a provider for server launch calls. Currently, provider defaults to digitalocean, but this default will be removed. ## [2025-04-02] ### Removed deprecated features - `GET /server/{machine_id}/info` deprecated in favor of `GET /token/{token}/servers/{machine_id}` - `token` entries per server were removed from `GET /token/{token}/servers` as they are redundant. - `flavor` dictionaries per server were removed from `GET /token/{token}/servers`. Use `flavor_slug` instead. ## [2025-03-31] ### Removed deprecated features - `POST /server/{machine_id}/autorenew/enable` was removed in favor of `PATCH /token/{token}/servers/{machine_id}` - `POST /server/{machine_id}/autorenew/disable` was removed in favor of `PATCH /token/{token}/servers/{machine_id}` - `POST /server/{machine_id}/rebuild` was removed in favor of `POST /token/{token}/servers/{machine_id}/rebuild` - `PATCH /server/{machine_id}` was removed in favor of `PATCH /token/{token}/servers/{machine_id}` - `POST /server/{machine_id}/start` was removed in favor of `POST /token/{token}/servers/{machine_id}/start` - `POST /server/{machine_id}/stop` was removed in favor of `POST /token/{token}/servers/{machine_id}/stop` ## [2025-03-28] ### Removed deprecated features - `POST /server/{machine_id}/topup` was removed in favor of `POST /token/{token}/servers/{machine_id}/topup` ## [2025-02-09] ### Added ## [2025-02-08] - `messages` to `GET /token/{token}/info` to show number of messages on the token. - `invoices` to `GET /token/{token}/info` to show number of invoices on the token. ### Added - `GET /aup` to return our Acceptable Use Policy. ## [2025-01-24] ### Removed deprecated features - `DELETE /server/{machine_id}` was removed in favor of `DELETE /token/{token}/servers/{machine_id}` - `POST /server/{machine_id}/forget` was removed in favor of `POST /token/{token}/servers/{machine_id}/forget` The rest of `/server/` endpoints will be removed in favor of `/token/{token}/servers/ endpoints. ## [2024-11-11] ### Changed - `GET /server/{machine_id}/info` deprecated in favor of `GET /token/{token}/servers/{machine_id}` - `POST /server/{machine_id}/autorenew/enable` deprecated in favor of `PATCH /token/{token}/servers/{machine_id}` - `POST /server/{machine_id}/autorenew/disable` deprecated in favor of `PATCH /token/{token}/servers/{machine_id}` - `POST /server/{machine_id}/rebuild` deprecated in favor of `POST /token/{token}/servers/{machine_id}/rebuild` - `POST /server/{machine_id}/start` deprecated in favor of `POST /token/{token}/servers/{machine_id}/start` - `POST /server/{machine_id}/stop` deprecated in favor of `POST /token/{token}/servers/{machine_id}/stop` - `POST /server/{machine_id}/forget` deprecated in favor of `POST /token/{token}/servers/{machine_id}/forget` - `POST /server/{machine_id}/topup` deprecated in favor of `POST /token/{token}/servers/{machine_id}/topup` - `DELETE /server/{machine_id}` deprecated in favor of `DELETE /token/{token}/servers/{machine_id}` - `PATCH /server/{machine_id}` deprecated in favor of `PATCH /token/{token}/servers/{machine_id}` In short, all `/server/` endpoints are being moved under `/token/{token}/servers/`. Note: `POST /token/{token}/servers/{machine_id}/topup` only supports the `days` argument. `token` was removed (it will use the token the server was launched with.) You cannot topup servers from different tokens when using this endpoint. It's not intended for tokens to topup other token's servers. ### Deprecated - `token` entries per server will be removed from `GET /token/{token}/servers` as they are redundant. - `flavor` dictionaries per server will be removed from `GET /token/{token}/servers`. Use `flavor_slug` instead. ### Removed - `token` removed from `GET /token/{token}/servers/{machine_id}`'s response as it is redundant. - `POST /server/{machine_id}/launch` was removed in favor of `POST /token/{token}/servers`. A `machine_id` will be returned for you. ## [2024-10-01] ### Removed deprecated features - Deprecated as of 2024-06-25: `GET /operatingsystems` is deprecated in favor of `GET /slugs/os` - Deprecated as of 2024-06-25: `GET /regions` is deprecated in favor of `GET /slugs/regions` - Deprecated as of 2024-06-25: `GET /flavors` is deprecated in favor of `GET /slugs/flavors` ## [2024-07-22] ## Added - `GET /token/{token}/servers/{machine_id}`, analogous to `GET /servers/{machine_id}/info`. However, the `flavor` object is not returned, only `flavor_slug`. Can reference to `/slugs/flavors` if need be. ## [2024-07-19] ### Added - Our Vultr backend should now support `user_data`, like how our DigitalOcean backend already has. - Vultr servers can now be rebuilt. It's possible there might be issues with using this feature on servers built before this code release, as far as SSH keys go. So you might not be able to get back in. This is why we said Vultr support is in beta! If this happens, let us know and we'll see what we can do. ### Other - Launching servers with the same SSH key as other servers should be faster. This only applies to servers launched now, so the second launch and later after today should be sped up just slightly. You may not notice this, but it should be more robust and it's another reason we recommend one SSH key per token. Once all servers have been deleted with a given SSH key, after 90 days the SSH keys should be removed as before. That currently doesn't apply to Vultr, but we are planning on fixing that. ## [2024-07-17] ### Changed - The ID format of transactions, invoices, and messages changed slightly. This one is shorter and sortable. Not likely to have any impact. ### Added - Query filtering support for `GET /token/{token}/servers` with `?include_deleted=false` (defaults to true), `?include_forgotten=false` (defaults to true), and `?hostname=foobar`, to return all servers matching that hostname, if any. ## [2024-06-25] ### Added - Vultr support is here! Pass `"provider": "vultr"` and be sure to use operating system and region options compatible with Vultr. The Vultr code seems to work but is not nearly as battle tested as the DigitalOcean code, so beware! ### Changed - `GET /operatingsystems` is deprecated in favor of `GET /slugs/os`. The response format changed as well. The deprecated endpoint only responds with DigitalOcean-specific items. - `GET /regions` is deprecated in favor of `GET /slugs/regions`. The response format changed as well. The deprecated endpoint only responds with DigitalOcean-specific items. - `GET /flavors` is deprecated in favor of `GET /slugs/flavors`. The response format changed as well. The deprecated endpoint only responds with DigitalOcean-specific items. ### Broken - All of your hard earned dummy servers have been deleted! They probably weren't doing you much good, anyway. (If you're confused by this, we have a dummy provider to create dummy servers with, that don't do anything...) ## [2024-06-21] ### Added - You can now launch a server under the "dummy" provider by passing `provider: "dummy"` to `POST /token/{token}/servers`. This is completely useless, however, and you do get billed for it! It's just for test purposes in preparation for more real providers. "digitalocean" is still the default, but you may pass it explicitly now. ### Changed - The successful response of `POST /token/{token}/servers` has been changed from HTTP 200 to HTTP 201. ## [2024-06-19] ### Changed `POST /server/{machine_id}/launch` is deprecated in favor of `POST /token/{token}/servers`. A `machine_id` will be returned for you (when calling the new endpoint.) ## [2024-06-18] ### Removed previously deprecated features - `/server/{machine_id}/info`'s `deleted` in favor of `deleted_at`. - `/token/{token}/info`'s `burn_rate` in favor of `burn_rate_cents`. - `payment` of `POST /token/{token}/add` in favor of `invoice`. ## [2024-05-22] ## Changed - `POST /server/{machine_id}/launch`: `days` can be unset if `autorenew` is set to `true`. Will default to 8 days in this case. ## [2024-02-26] ## Changed - `POST /token/{token}/add`: `legacy_polling=false` is the new default and its behavior is mandatory (see the 2024-01-03 entry). Polling the endpoint is highly discouraged. Use `GET /token/{token}/invoice/{invoice}` if you wish to poll, after `POST /token/{token}/add` which will return the invoice and its ID. ## Removed - `POST /server/{machine_id}/delete` in favor of `DELETE /server/{machine_id}`. - `POST /server/{machine_id}/destroy` in favor of `DELETE /server/{machine_id}`. ## [2024-01-03] Happy New Year! ## Added - Added `GET /token/{token}/invoice/{invoice}` to retrieve status of an individual invoice. - If you set `legacy_polling` to `false` when using `/token/{token}/add`, the backend will process payments for you in the background so you don't have to POST continously to make sure payments go through. This defaults to legacy polling being on, for legacy compatibility. In the future the default will probably change, either as this endpoint or another. You can use the afforementioned GET endpoint to poll if you are curious about when the payment is acknowledged. This is recommended over continous POSTing, and the (currently default) behavior of `legacy_polling` being `true` is now deprecated. ## Changed - Invoice's `id` type changed from a int to a string. ## [2023-10-31] ## Added - Added `suspended_at` datetime or null field to server info to indicate when a server was suspended, if ever. If you have a suspended server, check your token messages and respond. Suspended servers are powered off and cannot be powered on without manual intervention. - Added `suspended_servers` to token info response. This tells you how many non-deleted suspended servers are on your token. - Added `autorenew_servers` to token info response. This tells you how many non-deleted autorenew servers are on your token. ## [2023-10-02] ## Changed - Can no longer renew/topup a server to more than one year out. Autorenew is recommended instead. ## [2023-08-31] ## Added - Additional flavor types. ## [2023-07-30] ## Added - Set Cloud Init user data at server launch with optional `user_data` field. ## [2023-06-13] ## Changed - If a server fails to autorenew due to insufficient funds (maintain 7+ days expiration), it will be powered off to signal that the token has run out. To turn through the remaining balance you have to disable autorenew on the server and then power it on. If you top up a token, you have to manually power on the server after if it's been stopped. ## [2023-05-25] ## Added - `PATCH /server/{machine_id}` to update `hostname`, and/or `autorenew`. May supercede `POST /server/{machine_id}/autorenew/enable` and `disable` endpoints in the future. ## [2023-05-15] ## Changed - Messages (for tokens) will be deleted after 90 days. ## [2023-05-11] ## Added - `expired` property to token invoices, to easily determine if the invoice is expired or not. Only relevant if unpaid. ## Changed - `/token/{token}/add` also sends `invoice`. `payment` and `token` are now deprecated. ## [2023-05-03] ## Added - `/server/{machine_id}/info` now has a `deleted_by` field. Servers deleted before this feature will simply see `null` for this. ## Changed - `/server/{machine_id}/forget` no longer deletes the server from the database. It now sets `forgotten_at` as a signal that the server is to be ignored by clients. ## [2023-04-14] ## Added - `/token/{token}/info` now has `burn_rate_usd`. - `/token/{token}/info` now has `burn_rate_cents` which supercedes `burn_rate`. ## Changed - `/operatingsystems` endpoint now returns a dictionary with slightly more information about the operating system (namely, minimum disk space needed for it). - `/server/{machine ID}/launch` will now return a detailed 422 if the operating system won't fit on the flavor, rather than failing with an obscure 500. ## [2023-04-13] ## Added - `/changelog` endpoint. ## [2023-04-12] ## Changed - `/server/{machine ID}/launch` endpoint changed to 204 empty response. - `/server/{machine ID}/topup` endpoint changed to 204 empty response.