diff --git a/src/api_spec.md b/src/api_spec.md
new file mode 100644
index 0000000..f6a676a
--- /dev/null
+++ b/src/api_spec.md
@@ -0,0 +1,81 @@
+# API spec for communicating between the frontend and the backend
+
+## List of routes
+- `/routes`
+- `/routes/{id}`
+- `/stops/{id}`
+- `/path?lat={lattitude}&lon={longitude}&time={unix_epoch}`
+
+
+## `/routes`
+being a json list of urls to each of the available routes of the app, probably won't be used for core functionality but it'll be trivial to implement so might as well
+
+## `/routes/{id}`
+json object describing a route, I'm planning on this having an infinite cache time, if a route changes a new id will be made for the route after the change
+```json
+{
+  "_links":{
+    "self":{
+      "href":"https://$base_domain/routes/{id}"
+    },
+    // stops in order of when the bus reaches them
+    "stops": [{
+        "href":"https://$base_domain/stops/{id}",
+        "lattitude":{lattitude},
+        "longitude":{longitude}
+        }, 
+        ...
+    ]
+  },
+  "polyline": "whatever the route's polyline is"
+}
+```
+
+## `/stops/{id}`
+
+```json
+{
+  "_links":{
+    "self":{
+      "href":"https://$base_domain/stops/{id}"
+    },
+    // routes that make use of the stop in arbitrary order
+    "routes": [
+      {
+        "href":"https://$base_domain/routes/{id}",
+        "polyline": "{polyline}"
+      }
+    ]
+  }
+  "lattitude": {lattitude},
+  "longitude": {longitude}
+}
+```
+
+`/path?lat={lattitude}&lon={longitude}&time={unix_epoch}`
+```json
+{
+  "_links":{
+    "self":{
+      "href": "https://$base_domain/path?lat={lattitude}&lon={longitude}&time={unix_epoch}"
+    }
+    "path":[
+      {
+        "route":{
+            "href":"https://$base_domain/routes/{id}",
+            "polyline": "{polyline}"
+        },
+        "enter_bus":{
+            "href":"https://$base_domain/stops/{id}",
+            "lattitude": {lattitude},
+            "longitude": {longitude}
+        },
+        "exit_bus":{
+            "href":"https://$base_domain/stops/{id}",
+            "lattitude": {lattitude},
+            "longitude": {longitude}
+        },
+    ]
+  },
+}
+```