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 HTTP API, you first need to create an authorization token with suitable permissions.

You can run the following command in the nixbuild.net administration shell to generate a token that only is allowed to read information about builds. It can't be used for building, or uploading/downloading store paths.

nixbuild.net> tokens create -p build:read
-------------------------------------------------------------
ErkBCk8KCmJ1aWxkOnJlYWQYAyIICgYIBxICEAQiDQoLCAQSBzoFCgMYgAgyJgokCgIIGxIGCAUSAggFGhYKBAoCCAUKCAoGIIj8xNEGCgQaAggAEiQIABIgBFBr7DnfezvPl6qSSh1G89ni8b_Q_S_wZev-L__h3xAaQBc9YSyvewZtA4IHU_BSrhuiXEp6QWua1rxEK11PQ6POYpMSMdJFhl3UYm8MGgCO-S1tf1hvo3Ax0r-dCLyvLAMiIgogjhT641vbgmGJ7QLaih4faauWvTvNnkgQ3oUW4p-sPaw=
-------------------------------------------------------------

The token will expire at:
  2026-06-16 12:13:59Z

The token has the following permissions:
  build:read

It is recommended to create tokens with as few permissions as possible. You can also look into creating restricted "sub-tokens" through an operation called attenuation.

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. If needed, you can revoke tokens at any time.

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.