diff --git a/docs/api.md b/docs/api.md
index 51e1544f0a72..3f8288d018cf 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -95,6 +95,19 @@ The Loki server has the following API endpoints (_Note:_ Authentication is out o
   }
   ```
 
+- `GET /ready`
+
+  This endpoint returns 200 when Loki ingester is ready to accept traffic. If you're running Loki on Kubernetes, this endpoint can be used as readiness probe.
+
+- `GET /flush`
+
+  This endpoint triggers a flush of all in memory chunks in the ingester. Mainly used for local testing.
+
+- `GET /metrics`
+
+  This endpoint returns Loki metrics for Prometheus. See "[Operations > Observability > Metrics](./operations.md)" to have a list of exported metrics.
+
+
 ## Examples of using the API in a third-party client library
 
 1) Take a look at this [client](https://github.com/afiskon/promtail-client), but be aware that the API is not stable yet (Golang).
diff --git a/docs/promtail-api.md b/docs/promtail-api.md
new file mode 100644
index 000000000000..2d1cf892ab62
--- /dev/null
+++ b/docs/promtail-api.md
@@ -0,0 +1,22 @@
+# Promtail API
+
+Promtail features an embedded web server exposing a web console at `/` and the following API endpoints:
+
+- `GET /ready`
+
+  This endpoint returns 200 when Promtail is up and running, and there's at least one working target.
+
+- `GET /metrics`
+
+  This endpoint returns Promtail metrics for Prometheus. See "[Operations > Observability > Metrics](./operations.md)" to have a list of exported metrics.
+
+
+## Promtail web server config
+
+The web server exposed by Promtail can be configured in the promtail `.yaml` config file:
+
+```
+server:
+  http_listen_host: 127.0.0.1
+  http_listen_port: 9080
+```
diff --git a/docs/promtail.md b/docs/promtail.md
index 938ab6b93bc6..9d27e8f5175f 100644
--- a/docs/promtail.md
+++ b/docs/promtail.md
@@ -3,6 +3,7 @@
   * [Scrape Configs](#scrape-configs)
   * [Entry Parsing](#entry-parser)
   * [Deployment Methods](./promtail-setup.md)
+  * [Promtail API](./promtail-api.md)
   * [Config and Usage Examples](./promtail-examples.md)
   * [Troubleshooting](./troubleshooting.md)