Add Documentation to Ci Lint API

2 files changed, 48 insertions, 1 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index 96d94e08487..67ec502346e 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -41,8 +41,10 @@ following locations:
 - [Sidekiq metrics](sidekiq_metrics.md)
 - [System Hooks](system_hooks.md)
 - [Tags](tags.md)
-- [Users](users.md)
 - [Todos](todos.md)
+- [Users](users.md)
+- [Validate the .gitlab-ci.yaml](ci_lint.md)
+
 
 ### Internal CI API
 
diff --git a/doc/api/ci_lint.md b/doc/api/ci_lint.md
new file mode 100644
index 00000000000..2b169176dd6
--- /dev/null
+++ b/doc/api/ci_lint.md
@@ -0,0 +1,45 @@
+# Validate the .gitlab-ci.yaml
+
+Check whether your .gitlab-ci.yml file is valid.
+
+```
+POST ci/lint
+```
+
+| Attribute  | Type    | Required | Description |
+| ---------- | ------- | -------- | -------- |
+| `content`  | hash    | yes      | the .gitlab-ci.yaml content|
+
+```bash
+curl --request POST "https://gitlab.example.com/api/v3/ci/lint?content=YAML+Content"
+```
+
+Example response:
+
+* valid content
+
+```json
+{
+  "status": "valid",
+  "errors": []
+}
+```
+
+* invalid content
+
+```json
+{
+  "status": "invalid",
+  "errors": [
+    "variables config should be a hash of key value pairs"
+  ]
+}
+```
+
+* without the content attribute
+
+```json
+{
+  "error": "content is missing"
+}
+```