Skip to content

HTTP API Usage

nixbuild.net provides an HTTP API that allows users to retrieve information about builds, consumed CPU hours and more. The available API endpoints are detailed here.

Authorization

To start using the API, you first need to create an authorization token. The tokens used by nixbuild.net are based on Biscuit, giving users a flexible way of setting up advanced authorization policies for their nixbuild.net accounts. The Biscuit support is something that will be expanded upon and documented in the future. For now, you can treat the authorization tokens as plain API keys, ignoring the fact that they are Biscuit tokens.

Start out by creating a new authorization token in the nixbuild.net shell like this:

nixbuild.net> tokens create --read-only
-------------------------------------------------------------
EpABCiYKB2FjY291bnQYAyIJCgcIgAgSAhABMg4KDAoCCBsSBggDEgIYABIkCAASIFeRyO2t1bxV2ZlLJKkp4S97nCyAz1ieyrCLv_RzYI0EGkCYCkIllHyVVnfZwyh0zxcKO-iqgtHkkaudYvZE9wL6otfeMe-ATkGh0Gkz_KyLt_YEbt__X5DRJ6Tj_41Z35APIiIKIHmZTFwQzdy2GZadSXRFYscLTHnbb_spQgLonsqos2tv
-------------------------------------------------------------

It is strongly recommended that you use the --read-only option to create a token with limited permissions. So far, the nixbuild.net API only provides read-only operations, so it doesn't hurt limiting your tokens this way.

By default, tokens are valid for 1000 days. You can also set shorter expiration times, see tokens create --help.

The tokens you create are not stored in nixbuild.net. It is your responsibility to store your tokens safely. User-available token revocation is not possible at the moment, but will be in the future. If you need to revoke tokens, please contact [email protected].

Usage Example

Using the token we created above we can access the API with curl like this:

$ curl -s https://api.nixbuild.net/usage \
    -H 'Authorization: Bearer EpABCiYKB2FjY291bnQYAyIJCgcIgAgSAhABMg4KDAoCCBsSBggDEgIYABIkCAASIFeRyO2t1bxV2ZlLJKkp4S97nCyAz1ieyrCLv_RzYI0EGkCYCkIllHyVVnfZwyh0zxcKO-iqgtHkkaudYvZE9wL6otfeMe-ATkGh0Gkz_KyLt_YEbt__X5DRJ6Tj_41Z35APIiIKIHmZTFwQzdy2GZadSXRFYscLTHnbb_spQgLonsqos2tv'

{
  "billable_cpu_seconds": 316,
  "billable_build_count": 251
}

In the above example, we used the /usage API endpoint, which returns information about how many CPU hours you have used during a given period. To see all available endpoints and their parameters, see the API reference.