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 access 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 --name api-example -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

The token has the following name:
  api-example

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 30 days. You can select another expiration time with tokens create --ttl-seconds; see tokens create --help.

The secret tokens you create are not stored in nixbuild.net and are only shown once. It is your responsibility to store them safely. nixbuild.net retains the token metadata needed to list and 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.