1 files changed, 41 insertions, 0 deletions
diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md
new file mode 100644
index 00000000000..3b5008ccdb4
--- /dev/null
+++ b/doc/ci/api/builds.md
@@ -0,0 +1,41 @@
+# Builds API
+
+This API used by runners to receive and update builds.
+
+__Authentication is done by runner token__
+
+## Builds
+
+### Runs oldest pending build by runner
+
+    POST /ci/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" : ""
+}
+```
+
+
+### Update details of an existing build
+
+    PUT /ci/builds/:id
+
+Parameters:
+
+  * `id` (required) - The ID of a project
+  * `state` (optional) - The state of a build
+  * `trace` (optional) - The trace of a build