diff --git a/schemas/reflector.yaml b/schemas/reflector.yaml
index 4d3affa..e945097 100644
--- a/schemas/reflector.yaml
+++ b/schemas/reflector.yaml
@@ -1,7 +1,47 @@
 openapi: 3.0.3
 info:
   title: Bypass Censorship Reflector
-  description: The public API for the Bypass Censorship Reflector.
+  description: |
+    **The public API for the Bypass Censorship Reflector.**
+
+    This API is intended to be consumed by tools used for the distribution of mirror links for specific articles.
+    These tools may be browser extensions, desktop tools, dedicated web applications, or integrated into CMSs.
+
+    For any given URL, if a mirror is available, up to 3 kinds of link may be generated.
+    To generate a short link requires authentication with an API key, but both direct and onion links may be generated
+    without authentication.
+
+    Link Types
+    ----------
+
+    <dl>
+      <dt>Short Links (`short`)<dt>
+      <dd>
+        These are the most convenient for sharing due to their length, and fully support display of OpenGraph
+        tags in social media clients.
+      </dd>
+      <dt>Direct Links (`direct`)</dt>
+      <dd>
+        These are direct links to the mirror site, and fully support display of OpenGraph tags in social media clients.
+        They are less convenient to share due to increased length, however these are available for non-authenticated
+        users unlike the short links.
+      </dd>
+      <dt>Onion Links (`onion`)</dt>
+      <dd>
+        Where an Onion service has been deployed for a given website, this will return a link to the article on that
+        Onion service.
+        Visiting Onion services requires that users have downloaded, installed and configured a Tor-aware browser
+        such as Tor Browser or Onion Browser.
+      </dd>
+    </dl>
+    
+    Authentication
+    --------------
+    
+    For all endpoints, authentication is performed using an API key.
+    This is passed as a query parameter named "key".
+    The [/me](#/default/get_me) endpoint can be used to verify an API key without fetching a link.
+
   version: 0.0.1
 
 servers: