diff --git a/README.md b/README.md
new file mode 100644
index 0000000..598894e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# RandomRedditMemesAPI
+
+an API that returns random Reddit Submissions written in Java
+
+## build and run
+
+### build project
+first make sure you're using Gradle 6.8 and openjdk-jdk8
+
+to build the project just run:
+```
+gradle build
+```
+
+### run
+to execute the .jar archive you built before run:
+```
+java -jar ./build/libs/RandomRedditMemesAPI.jar
+```
+
+### run inside docker
+to execute the .jar file inside docker use docker-compose:
+```
+docker-compose -p RandomRedditMemesAPI up -docker
+```
+
+### build docker image
+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