diff --git a/doc/manual/api.xml b/doc/manual/api.xml
new file mode 100644
index 00000000..435af049
--- /dev/null
+++ b/doc/manual/api.xml
@@ -0,0 +1,338 @@
+
+
+ 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",
+ "releases": [],
+ "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",
+ "releases": [],
+ "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",
+ "releases": []
+}
+
+
+
+
+
+ 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",
+ "sha1hash": null,
+ "defaultpath": "log.html",
+ "type": "report",
+ "sha256hash": null,
+ "filesize": null,
+ "name": "",
+ "subtype": "testlog"
+ }
+ },
+ "finished": 1
+}
+
+
+
+
+
+
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index c9273cde..75e53152 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -63,6 +63,7 @@
+