hydra/doc/manual/src/api.md

Using the external API

To be able to create integrations with other services, Hydra exposes an external API that you can manage projects with.

The API is accessed over HTTP(s) where all data is sent and received as JSON.

Creating resources requires the caller to be authenticated, while retrieving resources does not.

The API does not have a separate URL structure for it's endpoints. Instead you request the pages of the web interface as application/json to use the API.

List projects

To list all the projects of the Hydra install:

GET /
Accept: application/json

This will give you a list of projects, where each project contains general information and a list of its job sets.

Example

curl -i -H 'Accept: application/json' \
    https://hydra.nixos.org

Note: this response is truncated

GET https://hydra.nixos.org/
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "displayname": "Acoda",
    "name": "acoda",
    "description": "Acoda is a tool set for automatic data migration along an evolving data model",
    "enabled": 0,
    "owner": "sander",
    "hidden": 1,
    "jobsets": [
      "trunk"
    ]
  },
  {
    "displayname": "cabal2nix",
    "name": "cabal2nix",
    "description": "Convert Cabal files into Nix build instructions",
    "enabled": 0,
    "owner": "simons@cryp.to",
    "hidden": 1,
    "jobsets": [
      "master"
    ]
  }
]

Get a single project

To get a single project by identifier:

GET /project/:project-identifier
Accept: application/json

Example

curl -i -H 'Accept: application/json' \
    https://hydra.nixos.org/project/hydra

GET https://hydra.nixos.org/project/hydra
HTTP/1.1 200 OK
Content-Type: application/json

{
  "description": "Hydra, the Nix-based continuous build system",
  "hidden": 0,
  "displayname": "Hydra",
  "jobsets": [
    "hydra-master",
    "hydra-ant-logger-trunk",
    "master",
    "build-ng"
  ],
  "name": "hydra",
  "enabled": 1,
  "owner": "eelco"
}

Get a single job set

To get a single job set by identifier:

GET /jobset/:project-identifier/:jobset-identifier
Content-Type: application/json

Example

curl -i -H 'Accept: application/json' \
    https://hydra.nixos.org/jobset/hydra/build-ng

GET https://hydra.nixos.org/jobset/hydra/build-ng
HTTP/1.1 200 OK
Content-Type: application/json

{
  "errormsg": "evaluation failed due to signal 9 (Killed)",
  "fetcherrormsg": null,
  "nixexprpath": "release.nix",
  "nixexprinput": "hydraSrc",
  "emailoverride": "rob.vermaas@gmail.com, eelco.dolstra@logicblox.com",
  "jobsetinputs": {
    "officialRelease": {
      "jobsetinputalts": [
        "false"
      ]
    },
    "hydraSrc": {
      "jobsetinputalts": [
        "https://github.com/NixOS/hydra.git build-ng"
      ]
    },
    "nixpkgs": {
      "jobsetinputalts": [
        "https://github.com/NixOS/nixpkgs.git release-14.12"
      ]
    }
  },
  "enabled": 0
}

List evaluations

To list the evaluations of a job set by identifier:

GET /jobset/:project-identifier/:jobset-identifier/evals
Content-Type: application/json

Example

curl -i -H 'Accept: application/json' \
    https://hydra.nixos.org/jobset/hydra/build-ng/evals

Note: this response is truncated

GET https://hydra.nixos.org/jobset/hydra/build-ng/evals
HTTP/1.1 200 OK
Content-Type: application/json

{
  "evals": [
    {
      "jobsetevalinputs": {
        "nixpkgs": {
          "dependency": null,
          "type": "git",
          "value": null,
          "uri": "https://github.com/NixOS/nixpkgs.git",
          "revision": "f60e48ce81b6f428d072d3c148f6f2e59f1dfd7a"
        },
        "hydraSrc": {
          "dependency": null,
          "type": "git",
          "value": null,
          "uri": "https://github.com/NixOS/hydra.git",
          "revision": "48d6f0de2ab94f728d287b9c9670c4d237e7c0f6"
        },
        "officialRelease": {
          "dependency": null,
          "value": "false",
          "type": "boolean",
          "uri": null,
          "revision": null
        }
      },
      "hasnewbuilds": 1,
      "builds": [
        24670686,
        24670684,
        24670685,
        24670687
      ],
      "id": 1213758
    }
  ],
  "first": "?page=1",
  "last": "?page=1"
}

Get a single build

To get a single build by its id:

GET /build/:build-id
Content-Type: application/json

Example

curl -i -H 'Accept: application/json' \
    https://hydra.nixos.org/build/24670686

GET /build/24670686
HTTP/1.1 200 OK
Content-Type: application/json

{
  "job": "tests.api.x86_64-linux",
  "jobsetevals": [
    1213758
  ],
  "buildstatus": 0,
  "buildmetrics": null,
  "project": "hydra",
  "system": "x86_64-linux",
  "priority": 100,
  "releasename": null,
  "starttime": 1439402853,
  "nixname": "vm-test-run-unnamed",
  "timestamp": 1439388618,
  "id": 24670686,
  "stoptime": 1439403403,
  "jobset": "build-ng",
  "buildoutputs": {
    "out": {
      "path": "/nix/store/lzrxkjc35mhp8w7r8h82g0ljyizfchma-vm-test-run-unnamed"
    }
  },
  "buildproducts": {
    "1": {
      "path": "/nix/store/lzrxkjc35mhp8w7r8h82g0ljyizfchma-vm-test-run-unnamed",
      "defaultpath": "log.html",
      "type": "report",
      "sha256hash": null,
      "filesize": null,
      "name": "",
      "subtype": "testlog"
    }
  },
  "finished": 1
}