Update format of documentation for CI APIdoc/ci-api-update

2 files changed, 40 insertions, 23 deletions

diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md
index b82f2d19b19..d100e261178 100644
--- a/doc/ci/api/builds.md
+++ b/doc/ci/api/builds.md
@@ -8,35 +8,45 @@ communication channel. For the consumer API see the
 
 ## Authentication
 
-Unique runner token is required to authenticate. You can provide build token
-using a `token` parameter, or by sending `BUILD-TOKEN` header that contains it.
+This API uses two types of authentication:
 
-`token` parameter and `BUILD-TOKEN` header can be interchangeable.
+1.   Unique runner's token
+
+     Token assigned to runner after it has been registered.
+
+2.   Using build authorization token
+
+     This is project's CI token that can be found in Continuous Integration
+     project settings.
+
+     Build authorization token can be passed as a parameter or a value of
+     `BUILD-TOKEN` header. This method are interchangeable.
 
 ## Builds
 
 ### Runs oldest pending build by runner
 
-    POST /builds/register
+    POST /ci/api/v1/builds/register
 
 Parameters:
 
-  * `token` (required) - The unique token of runner
+  * `token` (required) - Unique runner token
 
 
 ### Update details of an existing build
 
-    PUT /builds/:id
+    PUT /ci/api/v1/builds/:id
 
 Parameters:
 
   * `id` (required) - The ID of a project
+  * `token` (required) - Unique runner token
   * `state` (optional) - The state of a build
   * `trace` (optional) - The trace of a build
 
 ### Upload artifacts to build
 
-    POST /builds/:id/artifacts
+    POST /ci/api/v1/builds/:id/artifacts
 
 Parameters:
 
@@ -46,7 +56,7 @@ Parameters:
 
 ### Download the artifacts file from build
 
-    GET /builds/:id/artifacts
+    GET /ci/api/v1/builds/:id/artifacts
 
 Parameters:
 
@@ -55,7 +65,7 @@ Parameters:
 
 ### Remove the artifacts file from build
 
-    DELETE /builds/:id/artifacts
+    DELETE /ci/api/v1/builds/:id/artifacts
 
 Parameters:
 
diff --git a/doc/ci/api/runners.md b/doc/ci/api/runners.md
index c4716982357..2f01da4bd76 100644
--- a/doc/ci/api/runners.md
+++ b/doc/ci/api/runners.md
@@ -1,39 +1,46 @@
 # Runners API
 
-API used by runners to register and delete itselves.
+API used by runners to register and delete themselves.
 
 _**Note:** This API is intended to be used only by Runners as their own
 communication channel. For the consumer API see the
 [new Runners API](../../api/runners.md)._
 
+## Authentication
+
+This API uses two types of authentication:
+
+1.   Unique runner's token
+
+     Token assigned to runner after it has been registered.
+
+2.   Using runners' registration token
+
+     This is a token that can be found in project's settings.
+     It can be also found in Admin area » Runners settings.
+
+     There are two types of tokens you can pass - shared runner registration
+     token or project specific registration token.
+
 ## Runners
 
 ### Register a new runner
 
-__Authentication is done with a shared runner registration token or a project
-specific runner registration token.__
-
 Used to make GitLab CI aware of available runners.
 
-    POST /runners/register
+    POST /ci/api/v1/runners/register
 
 Parameters:
 
-  * `token` (required) - The registration token.
+  * `token` (required) - Registration token
 
-It is 2 types of token you can pass here.
-
-1. Shared runner registration token
-2. Project specific registration token
 
 ### Delete a runner
 
-__Authentication is done by using runner token.__
-
 Used to remove runner.
 
-    DELETE /runners/delete
+    DELETE /ci/api/v1/runners/delete
 
 Parameters:
 
-  * `token` (required) - The runner token.
+  * `token` (required) - Unique runner token