diff --git a/doc/api/commits.md b/doc/api/commits.md
index e4d436b8e52179882656f2f5a9fbc8642be5858f..6341440c58b9017eab77981d9cdc3e8f5d04f45e 100644
--- a/doc/api/commits.md
+++ b/doc/api/commits.md
@@ -213,8 +213,7 @@ Example response:
 
 ## Commit status
 
-Since GitLab 8.1, this is the new commit status API. The documentation in
-[ci/api/commits](../ci/api/commits.md) is deprecated.
+Since GitLab 8.1, this is the new commit status API.
 
 ### Get the status of a commit
 
diff --git a/doc/ci/api/README.md b/doc/ci/api/README.md
index cf9710ede577759608e4bbb28dfa802d4598e283..aea808007fcb21b7b2fb24fec13e8befca877b84 100644
--- a/doc/ci/api/README.md
+++ b/doc/ci/api/README.md
@@ -1,86 +1,22 @@
 # GitLab CI API
 
-## Resources
-
-- [Projects](projects.md)
-- [Runners](runners.md)
-- [Commits](commits.md)
-- [Builds](builds.md)
-
-
-## Authentication
-
-GitLab CI API uses different types of authentication depends on what API you use.
-Each API document has section with information about authentication you need to use.
-
-GitLab CI API has 4 authentication methods:
-
-* GitLab user token & GitLab url
-* GitLab CI project token
-* GitLab CI runners registration token
-* GitLab CI runner token
-
-
-### Authentication #1: GitLab user token & GitLab url
-
-Authentication is done by
-sending the `private-token` of a valid user and the `url` of an
-authorized GitLab instance via a query string along with the API
-request:
-
-    GET http://gitlab.example.com/ci/api/v1/projects?private_token=QVy1PB7sTxfy4pqfZM1U&url=http://demo.gitlab.com/
+## Purpose
 
-If preferred, you may instead send the `private-token` as a header in
-your request:
+Main purpose of GitLab CI API is to provide necessary data and context for
+GitLab CI Runners.
 
-    curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://gitlab.example.com/ci/api/v1/projects?url=http://demo.gitlab.com/"
+For consumer API take a look at this [documentation](../../api/README.md) where
+you will find all relevant information.
 
+## API Prefix
 
-### Authentication #2: GitLab CI project token
+Current CI API prefix is `/ci/api/v1`.
 
-Each project in GitLab CI has it own token. 
-It can be used to get project commits and builds information.
-You can use project token only for certain project.
+You need to prepend this prefix to all examples in this documentation, like:
 
-### Authentication #3: GitLab CI runners registration token
+    GET /ci/api/v1/builds/:id/artifacts
 
-This token is not persisted and is generated on each application start.
-It can be used only for registering new runners in system. You can find it on 
-GitLab CI Runners web page https://gitlab-ci.example.com/admin/runners
-
-### Authentication #4: GitLab CI runner token
-
-Every GitLab CI runner has it own token that allow it to receive and update 
-GitLab CI builds. This token exists of internal purposes and should be used only 
-by runners
-
-## JSON
-
-All API requests are serialized using JSON.  You don't need to specify
-`.json` at the end of API URL.
-
-## Status codes
-
-The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong, e.g. status code `400 Bad Request` is returned if a required attribute is missing from the request. The following list gives an overview of how the API functions generally behave.
-
-API request types:
-
-- `GET` requests access one or more resources and return the result as JSON
-- `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON
-- `GET`, `PUT` and `DELETE` return `200 OK` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
-- `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not.
-
-The following list shows the possible return codes for API requests.
-
-Return values:
+## Resources
 
-- `200 OK` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON
-- `201 Created` - The `POST` request was successful and the resource is returned as JSON
-- `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given
-- `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above
-- `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project
-- `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found
-- `405 Method Not Allowed` - The request is not supported
-- `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists
-- `422 Unprocessable` - The entity could not be processed
-- `500 Server Error` - While handling the request something went wrong on the server side
+- [Builds](builds.md)
+- [Runners](runners.md)
diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md
index 018ca22dbbd749fe3d2f386fee98f45df7722d90..d100e2611789891d3a89a7c8ff495e056255484d 100644
--- a/doc/ci/api/builds.md
+++ b/doc/ci/api/builds.md
@@ -1,85 +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": 48584,
-  "ref": "0.1.1",
-  "tag": true,
-  "sha": "d63117656af6ff57d99e50cc270f854691f335ad",
-  "status": "success",
-  "name": "pages",
-  "token": "9dd60b4f1a439d1765357446c1084c",
-  "stage": "test",
-  "project_id": 479,
-  "project_name": "test",
-  "commands": "echo commands",
-  "repo_url": "http://gitlab-ci-token:token@gitlab.example/group/test.git",
-  "before_sha": "0000000000000000000000000000000000000000",
-  "allow_git_fetch": false,
-  "options": {
-    "image": "docker:image",
-    "artifacts": {
-      "paths": [
-        "public"
-      ]
-    },
-    "cache": {
-      "paths": [
-        "vendor"
-      ]
-    }
-  },
-  "timeout": 3600,
-  "variables": [
-    {
-      "key": "CI_BUILD_TAG",
-      "value": "0.1.1",
-      "public": true
-    }
-  ],
-  "depends_on_builds": [
-    {
-      "id": 48584,
-      "ref": "0.1.1",
-      "tag": true,
-      "sha": "d63117656af6ff57d99e50cc270f854691f335ad",
-      "status": "success",
-      "name": "build",
-      "token": "9dd60b4f1a439d1765357446c1084c",
-      "stage": "build",
-      "project_id": 479,
-      "project_name": "test",
-      "artifacts_file": {
-        "filename": "artifacts.zip",
-        "size": 0
-      }
-    }
-  ]
-}
-```
+  * `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
diff --git a/doc/ci/api/commits.md b/doc/ci/api/commits.md
deleted file mode 100644
index 871de7abcce18ccd03451140cca3b49c40aa08c5..0000000000000000000000000000000000000000
--- a/doc/ci/api/commits.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# Commits API
-
-**DEPRECATED**
-
-Since GitLab 8.1, there is a new commit status API. Please see the [revised
-documentation](../../api/commits.md#commit-status).
-
----
-
-__Authentication is done by GitLab CI project token__
-
-## Commits
-
-### Retrieve all commits per project
-
-Get list of commits per project
-
-    GET /ci/commits
-
-Parameters:
-
-  * `project_id` (required) - The ID of a project
-  * `project_token` (requires) - Project token
-  * `page` (optional)
-  * `per_page` (optional) - items per request (default is 20)
-
-Returns:
-
-```json
-[{
-  "id": 3,
-  "ref": "master",
-  "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
-  "project_id": 2,
-  "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
-  "created_at": "2014-11-05T09:46:35.247Z",
-  "status": "success",
-  "finished_at": "2014-11-05T09:46:44.254Z",
-  "duration": 5.062692165374756,
-  "git_commit_message": "wow\n",
-  "git_author_name": "Administrator",
-  "git_author_email": "admin@example.com",
-  "builds": [{
-    "id": 7,
-    "project_id": 2,
-    "ref": "master",
-    "status": "success",
-    "finished_at": "2014-11-05T09:46:44.254Z",
-    "created_at": "2014-11-05T09:46:35.259Z",
-    "updated_at": "2014-11-05T09:46:44.255Z",
-    "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
-    "started_at": "2014-11-05T09:46:39.192Z",
-    "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
-    "runner_id": 1,
-    "coverage": null,
-    "commit_id": 3
-  }]
-}]
-```
-
-### Create commit
-
-Inform GitLab CI about new commit you want it to build.
-
-__If commit already exists in GitLab CI it will not be created__
-
-
-    POST /ci/commits
-
-Parameters:
-
-  * `project_id` (required) - The ID of a project
-  * `project_token` (requires) - Project token
-  * `data` (required) -  Push data. For example see comment in `lib/api/commits.rb`
-
-Returns:
-
-```json
-{
-  "id": 3,
-  "ref": "master",
-  "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
-  "project_id": 2,
-  "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
-  "created_at": "2014-11-05T09:46:35.247Z",
-  "status": "success",
-  "finished_at": "2014-11-05T09:46:44.254Z",
-  "duration": 5.062692165374756,
-  "git_commit_message": "wow\n",
-  "git_author_name": "Administrator",
-  "git_author_email": "admin@example.com",
-  "builds": [{
-    "id": 7,
-    "project_id": 2,
-    "ref": "master",
-    "status": "success",
-    "finished_at": "2014-11-05T09:46:44.254Z",
-    "created_at": "2014-11-05T09:46:35.259Z",
-    "updated_at": "2014-11-05T09:46:44.255Z",
-    "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf",
-    "started_at": "2014-11-05T09:46:39.192Z",
-    "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898",
-    "runner_id": 1,
-    "coverage": null,
-    "commit_id": 3
-  }]
-}
-```
diff --git a/doc/ci/api/projects.md b/doc/ci/api/projects.md
deleted file mode 100644
index fe6b1c01352b35216e7d09f63321231e8a3cc5b7..0000000000000000000000000000000000000000
--- a/doc/ci/api/projects.md
+++ /dev/null
@@ -1,149 +0,0 @@
-# Projects API
-
-This API is intended to aid in the setup and configuration of
-projects on GitLab CI.
-
-__Authentication is done by GitLab user token & GitLab url__
-
-## Projects
-
-### List Authorized Projects
-
-Lists all projects that the authenticated user has access to.
-
-```
-GET /ci/projects
-```
-
-Returns:
-
-```json
-[
-  {
-    "id" : 271,
-    "name" : "gitlabhq",
-    "timeout" : 1800,
-    "token" : "iPWx6WM4lhHNedGfBpPJNP",
-    "default_ref" : "master",
-    "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
-    "path" : "gitlab/gitlab-shell",
-    "always_build" : false,
-    "polling_interval" : null,
-    "public" : false,
-    "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
-    "gitlab_id" : 3
-  },
-  {
-    "id" : 272,
-    "name" : "gitlab-ci",
-    "timeout" : 1800,
-    "token" : "iPWx6WM4lhHNedGfBpPJNP",
-    "default_ref" : "master",
-    "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
-    "path" : "gitlab/gitlab-shell",
-    "always_build" : false,
-    "polling_interval" : null,
-    "public" : false,
-    "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
-    "gitlab_id" : 4
-  }
-]
-```
-
-### List Owned Projects
-
-Lists all projects that the authenticated user owns.
-
-```
-GET /ci/projects/owned
-```
-
-Returns:
-
-```json
-[
-  {
-    "id" : 272,
-    "name" : "gitlab-ci",
-    "timeout" : 1800,
-    "token" : "iPWx6WM4lhHNedGfBpPJNP",
-    "default_ref" : "master",
-    "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell",
-    "path" : "gitlab/gitlab-shell",
-    "always_build" : false,
-    "polling_interval" : null,
-    "public" : false,
-    "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
-    "gitlab_id" : 4
-  }
-]
-```
-
-### Single Project
-
-Returns information about a single project for which the user is
-authorized.
-
-    GET /ci/projects/:id
-
-Parameters:
-
-  * `id` (required) - The ID of the GitLab CI project
-
-### Create Project
-
-Creates a GitLab CI project using GitLab project details.
-
-    POST /ci/projects
-
-Parameters:
-
-  * `name` (required) - The name of the project
-  * `gitlab_id` (required) - The ID of the project on the GitLab instance
-  * `default_ref` (optional) - The branch to run on (default to `master`)
-
-### Update Project
-
-Updates a GitLab CI project using GitLab project details that the
-authenticated user has access to.
-
-    PUT /ci/projects/:id
-
-Parameters:
-
-  * `name` - The name of the project
-  * `default_ref` - The branch to run on (default to `master`)
-
-### Remove Project
-
-Removes a GitLab CI project that the authenticated user has access to.
-
-    DELETE /ci/projects/:id
-
-Parameters:
-
-  * `id` (required) - The ID of the GitLab CI project
-
-### Link Project to Runner
-
-Links a runner to a project so that it can make builds (only via
-authorized user).
-
-    POST /ci/projects/:id/runners/:runner_id
-
-Parameters:
-
-  * `id` (required) - The ID of the GitLab CI project
-  * `runner_id` (required) - The ID of the GitLab CI runner
-
-### Remove Project from Runner
-
-Removes a runner from a project so that it can not make builds (only
-via authorized user).
-
-    DELETE /ci/projects/:id/runners/:runner_id
-
-Parameters:
-
-  * `id` (required) - The ID of the GitLab CI project
-  * `runner_id` (required) - The ID of the GitLab CI runner
\ No newline at end of file
diff --git a/doc/ci/api/runners.md b/doc/ci/api/runners.md
index e9033aeacd55b79252ccf4e3438b63932ebec4da..2f01da4bd76c46f45466c5e95a0561f9659998f5 100644
--- a/doc/ci/api/runners.md
+++ b/doc/ci/api/runners.md
@@ -1,81 +1,46 @@
 # Runners API
 
+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)._
 
-## Runners
-
-### Retrieve all runners
+## Authentication
 
-__Authentication is done by GitLab user token & GitLab url__
+This API uses two types of authentication:
 
-Used to get information about all runners registered on the GitLab CI
-instance.
+1.   Unique runner's token
 
-    GET /ci/runners
+     Token assigned to runner after it has been registered.
 
-Returns:
+2.   Using runners' registration token
 
-```json
-[
-  {
-    "id" : 85,
-    "token" : "12b68e90394084703135"
-  },
-  {
-    "id" : 86,
-    "token" : "76bf894e969364709864"
-  },
-]
-```
+     This is a token that can be found in project's settings.
+     It can be also found in Admin area » Runners settings.
 
-### Register a new runner
+     There are two types of tokens you can pass - shared runner registration
+     token or project specific registration token.
 
+## Runners
 
-__Authentication is done with a Shared runner registration token or a project Specific runner registration token__
+### Register a new runner
 
 Used to make GitLab CI aware of available runners.
 
-    POST /ci/runners/register
+    POST /ci/api/v1/runners/register
 
 Parameters:
 
-  * `token` (required) - The registration token. It is 2 types of token you can pass here. 
+  * `token` (required) - Registration token
 
-1. Shared runner registration token
-2. Project specific registration token
-
-Returns:
-
-```json
-{
-  "id" : 85,
-  "token" : "12b68e90394084703135"
-}
-```
 
 ### Delete a runner
 
+Used to remove runner.
 
-__Authentication is done by runner token__
-
-Used to removing runners.
-
-    DELETE /ci/runners/delete
+    DELETE /ci/api/v1/runners/delete
 
 Parameters:
 
-  * `token` (required) - The runner token.
-
-Returns:
-
-```json
-{
-  "id" : 1,
-  "token" : "d14963981a428f70121777e50643d1",
-  "created_at" : "2015-02-26T11:39:39.232Z",
-  "updated_at" : "2015-02-26T11:39:39.232Z",
-  "description" : "awesome runner"
-}
-```
+  * `token` (required) - Unique runner token