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