1 files changed, 52 insertions, 20 deletions
diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md
index 3b5008ccdb4..d100e261178 100644
--- a/doc/ci/api/builds.md
+++ b/doc/ci/api/builds.md
@@ -1,41 +1,73 @@
 # Builds API
 
-This API used by runners to receive and update builds.
+API used by runners to receive and update builds.
 
-__Authentication is done by runner token__
+_**Note:** This API is intended to be used only by Runners as their own
+communication channel. For the consumer API see the
+[Builds API](../../api/builds.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 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 /ci/builds/register
+    POST /ci/api/v1/builds/register
 
 Parameters:
 
-  * `token` (required) - The unique token of runner
-
-Returns:
-
-```json
-{
-  "id" : 79,
-  "commands" : "",
-  "path" : "",
-  "ref" : "",
-  "sha" : "",
-  "project_id" : 6,
-  "repo_url" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
-  "before_sha" : ""
-}
-```
+  * `token` (required) - Unique runner token
 
 
 ### Update details of an existing build
 
-    PUT /ci/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 /ci/api/v1/builds/:id/artifacts
+
+Parameters:
+
+  * `id` (required) - The ID of a build
+  * `token` (required) - The build authorization token
+  * `file` (required) - Artifacts file
+
+### Download the artifacts file from build
+
+    GET /ci/api/v1/builds/:id/artifacts
+
+Parameters:
+
+  * `id` (required) - The ID of a build
+  * `token` (required) - The build authorization token
+
+### Remove the artifacts file from build
+
+    DELETE /ci/api/v1/builds/:id/artifacts
+
+Parameters:
+
+  * ` id` (required) - The ID of a build
+  * `token` (required) - The build authorization token