From bdb420d863350008782ef33fa8893d66bb8bd1c2 Mon Sep 17 00:00:00 2001
From: Mark Fletcher <mark@gitlab.com>
Date: Tue, 16 Jan 2018 08:29:48 +0000
Subject: [PATCH] Expand documentation for Runners API

- Document Registation - POST `/runners/`
- Document Deletion - DELETE `/runners/`
- Document Verification - POST `/runners/verify/
---
 ...42067-document-runner-registration-api.yml |  5 ++
 doc/api/runners.md                            | 83 +++++++++++++++++++
 2 files changed, 88 insertions(+)
 create mode 100644 changelogs/unreleased/docs-42067-document-runner-registration-api.yml

diff --git a/changelogs/unreleased/docs-42067-document-runner-registration-api.yml b/changelogs/unreleased/docs-42067-document-runner-registration-api.yml
new file mode 100644
index 00000000000..6b507174044
--- /dev/null
+++ b/changelogs/unreleased/docs-42067-document-runner-registration-api.yml
@@ -0,0 +1,5 @@
+---
+title: Expand documentation for Runners API
+merge_request: 16484
+author:
+type: other
diff --git a/doc/api/runners.md b/doc/api/runners.md
index f384ac57bfe..3ca07ce9795 100644
--- a/doc/api/runners.md
+++ b/doc/api/runners.md
@@ -411,3 +411,86 @@ DELETE /projects/:id/runners/:runner_id
 ```
 curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners/9"
 ```
+
+## Register a new Runner
+
+Register a new Runner for the instance.
+
+```
+POST /runners
+```
+
+| Attribute   | Type    | Required | Description         |
+|-------------|---------|----------|---------------------|
+| `token`     | string  | yes      | Registration token ([Read how to obtain a token](../ci/runners/README.md)) |
+| `description`| string | no       | Runner's description|
+| `info`       | hash   | no       | Runner's metadata   |
+| `active`     | boolean| no       | Whether the Runner is active   |
+| `locked`     | boolean| no       | Whether the Runner should be locked for current project |
+| `run_untagged` | boolean | no | Whether the Runner should handle untagged jobs |
+| `tag_list` | Array[String] | no | List of Runner's tags |
+| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job |
+
+```
+curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=ipzXrMhuyyJPifUt6ANz" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
+```
+
+Response:
+
+| Status    | Description                     |
+|-----------|---------------------------------|
+| 201       | Runner was created              |
+
+Example response:
+
+```json
+{
+    "id": "12345",
+    "token": "6337ff461c94fd3fa32ba3b1ff4125"
+}
+```
+
+## Delete a registered Runner
+
+Deletes a registed Runner.
+
+```
+DELETE /runners
+```
+
+| Attribute   | Type    | Required | Description         |
+|-------------|---------|----------|---------------------|
+| `token`     | string  | yes      | Runner's authentication token  |
+
+```
+curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=ebb6fc00521627750c8bb750f2490e"
+```
+
+Response:
+
+| Status    | Description                     |
+|-----------|---------------------------------|
+| 204       | Runner was deleted              |
+
+## Verify authentication for a registered Runner
+
+Validates authentication credentials for a registered Runner.
+
+```
+POST /runners/verify
+```
+
+| Attribute   | Type    | Required | Description         |
+|-------------|---------|----------|---------------------|
+| `token`     | string  | yes      | Runner's authentication token  |
+
+```
+curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=ebb6fc00521627750c8bb750f2490e"
+```
+
+Response:
+
+| Status    | Description                     |
+|-----------|---------------------------------|
+| 200       | Credentials are valid           |
+| 403       | Credentials are invalid         |