Skip to content

HTTP API Reference

Base URL: https://api.nixbuild.net

Bearer authentication is used, an authorization token must be provided in an Authorization: Bearer <TOKEN> header for each API request.

Common Concepts

Build Status

Possible build status values:

  • built
  • build_failed
  • cancelled
  • timeout
  • internal_error
  • out_of_memory
  • max_memory_exceeded
  • client_disconnect
  • client_error
  • pending
  • running

Build Output

Built output objects have the following schema:

{
  name : string,
  path : string,
  nar_hash : string,
  nar_size_bytes : integer number
}

Build

Build objects have the following schema:

{
  build_id : integer number,
  create_time : ISO 8601 string,
  start_time : ISO 8601 string,
  queue_time_seconds : decimal number,
  duration_seconds: null | decimal number,
  build_status : build status string (see above), 
  status_message : null | string,
  cpu_count : integer number,
  allocated_megabytes : integer number,
  cpu_seconds : integer number,
  peak_memory_use_kilobytes : null | integer number,
  peak_storage_use_kilobytes : null | integer number,
  derivation_path : string,
  outputs : array of build output objects (see above),
  system : string,
  tags : object
}

Endpoints

GET /builds

Query Parameters

  • tags optional

Filter on tags, by specifying a comma-separated sequence of <TAG>:<VALUE> pairs.

Tags can come from either top-level attributes (prefixed with NIXBUILDNET_TAG_) in derivations, or from SSH session environment variables (with same prefix). See SSH Environment and Nix Derivation.

  • create_time_from optional

Query for builds whose creation time is greater or equal to this parameter (in ISO 8601 date or date/time format).

  • create_time_to optional

Query for builds whose creation time is less than this parameter (in ISO 8601 date or date/time format).

  • status optional

Filter on status by specifying one or multiple (comma-separated) status values (see Build Status).

  • limit optional

Integer ceiling on the number of builds to return. Defaults to 500.

  • derivation_path optional

Query for builds of a specific derivation.

Response Body

The response body is a JSON array of objects of "build" type (see Build). The builds are ordered by creation time, latest first.

GET /build/summary

Query Parameters

  • tags optional

Filter on tags, by specifying a comma-separated sequence of <TAG>:<VALUE> pairs.

Tags can come from either top-level attributes (prefixed with NIXBUILDNET_TAG_) in derivations, or from SSH session environment variables (with same prefix). See SSH Environment and Nix Derivation.

  • create_time_from optional

Query for builds whose creation time is greater or equal to this parameter (in ISO 8601 date or date/time format).

  • create_time_to optional

Query for builds whose creation time is less than this parameter (in ISO 8601 date or date/time format).

  • status optional

Filter on status by specifying one or multiple (comma-separated) status values (see Build Status).

Response Body

The response is a JSON object of the following schema:

{
  build_count : integer number,
  running_build_count : integer number,
  discarded_build_count : integer number,
  failed_build_count : integer number,
  successful_build_count : integer number,
  total_cpu_seconds : integer number,
  billable_cpu_seconds : integer number,
  total_duration_seconds : decimal number,
  wall_time_seconds : decimal number,
  total_output_nar_size_kilobytes : integer number
}

GET /builds/:id

Response Body

The response body is a JSON object of "build" type (see Build).

GET /usage

Query Parameters

  • from optional

Query for builds whose stop date is greater or equal to this parameter (in ISO 8601 date format).

  • to optional

Query for builds whose stop date is less than this parameter (in ISO 8601 date format).

Response Body

The response is a JSON object of the following schema:

{
  billable_cpu_seconds : integer number,
  billable_build_count : integer number
}