diff --git a/url/examples.json b/url/examples.json
new file mode 100644
index 0000000..2029b8d
--- /dev/null
+++ b/url/examples.json
@@ -0,0 +1,33 @@
+{
+    "list": [{
+        "title": "List your shortened URLs",
+        "description": "List the token holder's shortened URLs",
+        "request": {
+        },
+        "response": {
+            "urlPairs": [{
+                "shortURL": "https://m3o.one/u/f8f3f83f3f83g",
+                "destinationURL": "https://mysite.com/this-is-a-rather-long-web-address",
+                "owner": "owner-id"
+            }]
+        }
+    }],
+    "shorten": [{
+        "title": "Shorten a long URL",
+        "request": {
+            "destinationURL": "https://mysite.com/this-is-a-rather-long-web-address"
+        },
+        "response": {
+            "shortURL": "https://m3o.one/u/f8f3f83f3f83g"
+        }
+    }],
+    "proxy": [{
+        "title": "Resolve a short URL to a long destination URL",
+        "request": {
+            "shortURL": "f8f3f83f3f83g"
+        },
+        "response": {
+            "destinationURL": "https://mysite.com/this-is-a-rather-long-web-address"
+        }
+    }]
+}
\ No newline at end of file
diff --git a/url/proto/url.proto b/url/proto/url.proto
index 9658aae..2fe9f0b 100644
--- a/url/proto/url.proto
+++ b/url/proto/url.proto
@@ -10,6 +10,7 @@ service Url {
 	rpc Proxy(ProxyRequest) returns (ProxyResponse) {}
 }
 
+// Shortens a destination URL and returns a full short URL.
 message ShortenRequest {
 	string destinationURL = 1;
 }
@@ -24,6 +25,8 @@ message URLPair {
 	string owner = 3;
 }
 
+// List shortened URLs. It has no input parameters, as it will take
+// the user ID from the token and list the user's (caller's) shortened URLs.
 message ListRequest {
 }
 
@@ -31,7 +34,12 @@ message ListResponse {
 	repeated URLPair urlPairs = 1;
 }
 
+// Proxy returns the destination URL of a short URL.
+// Proxy resolves even URLs not owned by the token holder,
+// unlike the List endpoint.
 message ProxyRequest {
+	// short url ID, without the domain, eg. if your short URL is
+	// `m3o.one/u/someshorturlid` then pass in `someshorturlid`
 	string shortURL = 1;
 }