Skip to the page

Using the API

Versioning

One major version, v1, in every path, and a version date for what it holds today.

v1 and the version date

Every path starts with /v1. The API also has a version date, today 2026-11-05, which is the OpenAPI document's info.version and is sent on answers to CLI sessions as the rykloud-api-version header. Each operation records the version that added it (x-rykloud-since) and whether it is stable or beta (x-rykloud-stability); every operation today is stable.

An operation's id (like environments.stop) is stable for the life of v1. Operations, fields and error codes are added as Rykloud grows, so read answers tolerantly: ignore fields you do not know, and treat an unknown error code by its status.

The OpenAPI document

The API publishes itself as OpenAPI 3.1, generated from the same route table that decides which routes a session may call, so the document cannot list a route the API does not serve. This reference is drawn from it, and a copy of the version shown here is at /docs/openapi.json.

curl https://api.rykloud.com/v1/public/openapi.json

The CLI's version

The CLI names itself in its User-Agent as rykloud/<version>. Answers to it carry rykloud-cli-latest (the newest release, so it can tell you to upgrade) and rykloud-cli-minimum. A CLI older than the minimum is answered 400 cli_too_old with detail.minimum. These docs describe release 0.1.0; rykloud version prints yours and the API version it speaks.