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,
  restart_of_build_id : null | integer number,
  restarted_as_build_id : null | integer number
}

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 /builds/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 /builds/:id/url¶

Returns a signed web URL that can be used to retrieve details about the build, including the build log.

Query Parameters¶

ttl_seconds optional

Response Body¶

The response is a JSON object of the following schema:

{
  build_id : integer number,
  url : string,
  expires_at : ISO 8601 string
}

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
}