Skip to content
HostupDevelopers
GuidesAPI referenceSupport

Versioning

Checked against the API code 3 November 2026

The public API is version 2. Build on it and nothing else.

What the public API is

Section titled “What the public API is”

The public API is every endpoint in the API reference and in openapi.json. All of them start with /api/v2/ except GET /api/jobs/{jobId}. You poll that one to follow a job that an action started. Jobs

The version is part of the path. There is no version header to send.

What counts as a breaking change

Section titled “What counts as a breaking change”

A change breaks an integration when code that worked before stops working. For example:

  • An endpoint, a field or an enum value is removed or renamed.
  • A field changes type or unit.
  • A parameter or body field that was optional becomes required.
  • An endpoint needs a scope it did not need before.
  • A status code or an error code changes meaning.

These changes do not break a client built as Build for change says:

  • A new endpoint.
  • A new field in a response.
  • A new optional parameter or body field.
  • A new enum value.
  • A new error code.

Build for change

Section titled “Build for change”
  • Ignore response fields you do not know.
  • Handle an enum value you do not know in a default branch. Do not fail on it.
  • Branch on the error code, never on detail. Errors and retries
  • Handle an error code you do not know by its HTTP status. Which errors to retry says what to do for each status. Show its detail to a person. It is written for people to read.
  • Store IDs as opaque strings. IDs
  • Move off anything marked deprecated. Deprecations
  • Read the changelog when you update your integration.

How changes are announced

Section titled “How changes are announced”

Every change you could notice goes in the changelog, newest first, under the date of the change. What counts as a breaking change says which of them can stop code that works today.

There is no fixed notice period for a breaking change or a deprecation today. Read the changelog before you update your integration. Look for the deprecation marks below as well.

Deprecations

Section titled “Deprecations”

An endpoint, parameter or field that is going away is marked deprecated. Its reference page shows a Deprecated box on an endpoint and a deprecated label next to a parameter or field. In openapi.json it has deprecated: true. Its description says what to do instead. POST /api/v2/vps/{id}/actions/reset-ssh-keys is one example.

Move off it when you see the mark. A deprecated endpoint can already answer only with an error that names the replacement. GET /api/v2/vps/{id}/routed-ipv6 always answers 410 routed_ipv6_moved, for example.

Paths outside the public API

Section titled “Paths outside the public API”

The client area in your browser calls many other paths under /api/. Some of them sit under /api/v2/ but have no page in the reference. They are built for the client area. They can change or disappear at any time, without a changelog entry. Do not build on them.

Some older paths answer with a Deprecation header and a Link header. Deprecation is the date the path was deprecated, as @ followed by Unix seconds. The Link entry with rel="successor-version" names the path to use instead. For example, GET /api/vps-accounts answers with:

Response headers
Deprecation: @1776384000
Link: <https://developer.hostup.se/>; rel="deprecation"; type="text/html", </api/v2/vps>; rel="successor-version"

Use the successor only when it has a page in the API reference. These older paths send no Sunset header. Like the other paths in this section, they can stop working without notice. Move off them.

Next: Changelog