diff --git a/README.md b/README.md
index a66101b514..fc8241140d 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ A Loki-based logging stack consists of 3 components:
 
 For instructions on getting started with Loki, see [our getting started docs](./production/README.md).
 
-For the beginnings of documentation on how to use Loki, see [our usage docs](./docs/usage.md).
+For the beginnings of documentation on how to use Loki, see [our usage docs](./docs/usage.md).  [API documentation](./docs/api.md) is also available.
 
 ## Getting Help
 
diff --git a/docs/api.md b/docs/api.md
index dab39ea1ae..ae1686509e 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,15 +1,27 @@
+# Loki API
 
-## API
+## Authentication
 
-*nb* Authentication is out of scope for this project.  You are expected to run an
-authenticating reverse proxy in front of our services, such as an Nginx with basic
-auth or a OAuth2 proxy.
+*nb* Authentication is out of scope for this project.
+You are expected to run an authenticating reverse proxy in front of our services, such as an Nginx with basic auth or a OAuth2 proxy.
+
+Loki is a multitenant system; requests and data for tenant A are isolated from tenant B.
+Requests to the Loki API should include an HTTP header (`X-Scope-OrgID`) identifying the tentant for the request.
+Tenant IDs can be any alphanumeric string; limiting them to 20 bytes is reasonable.
+
+Loki can be run in "single-tenant" mode where the `X-Scope-OrgID` header is not required.
+In this situation, the tenant ID is defaulted to be `fake`.
+
+## REST API
 
 There are 4 API endpoints:
 
 - `POST /api/prom/push`
 
-  For sending log entries, expects a snappy compressed proto in the HTTP Body.
+  For sending log entries, expects a snappy compressed proto in the HTTP Body:
+
+  - [ProtoBuffer defition](/pkg/logproto/logproto.proto)
+  - [Golang client library](/pkg/promtail/client.go)
 
 - `GET /api/prom/query`