diff --git a/README.md b/README.md
index 3d8614e..598894e 100644
--- a/README.md
+++ b/README.md
@@ -30,3 +30,37 @@ if you want to build a full docker image run:
 docker build .
 ```
 alternatively you can use `./docker/docker-compose.yml`
+
+## API
+
+the baseurl for the API is: `http://127.0.0.1/api/v1`
+
+### subreddits
+
+subreddit syntax `[baseurl]/r/[subreddit]/[type]`
+
+[type] syntax
+* `all` - returns the first 100 submissions of the subreddits page
+* `random` - returns one random submission of the first 100
+* `[0-99]` - returns a specific one
+* if undefined returns random
+
+the response looks like:
+```
+{
+    "subs":[{
+        "score": Integer,
+        "nsfw": Boolean,
+        "author": String,
+        "text": String,
+        "time": Integer,
+        "title": String,
+        "downvotes": Integer,
+        "permalink": String,
+        "subreddit": String,
+        "url": String,
+    }],
+    "error": Boolean/String,
+    "type":String
+}
+```
\ No newline at end of file