Getting started with the API

The API is documented in full inside the portal, under API keys. This page covers the things worth knowing before you read it.

The base URL follows the panel

The API lives under the control panel's own hostname, at /api/v1.

The panel is at cloud.kumodns.com, so the base URL is https://cloud.kumodns.com/api/v1. The documentation inside the portal always shows the base URL for the account you are signed in to — which is the reason to read it there rather than copying a URL from a web page.

Put the base URL in configuration, not in your source. A client with the hostname compiled into it is a client that breaks on the day of a migration, in a way that looks like an outage.

Authenticating

Every request carries your API key. Keys are per account and are subject to the same plan limits the portal enforces — the API is not a way around a zone or record cap.

Design your client for the boring cases

• Handle a non-2xx response. A quota reached, a zone that no longer exists, and a revoked key all look like failure and mean different things.
• Do not retry blindly. A failed create that is retried can become two records.
• Log what you sent, not just what came back. When a record appears that nobody meant to create, the request body is the evidence.
• Treat a 5xx as unknown, not as failed. Check the state before you re-send.

Changes made through the API are ordinary changes

They publish to all four nameservers exactly like a change made in the portal, and they are recorded in Time Machine the same way. A script that goes wrong at 3am is recoverable for the same reason a person who goes wrong at 3am is.

Before you automate deletion

Give the script the smallest job that does what you need, and test it against a zone you do not care about. A loop with a wrong filter deletes correctly and completely.

Last reviewed 2026-09-20.