diff --git a/username_api.raml b/username_api.raml
new file mode 100644
index 0000000..56a5189
--- /dev/null
+++ b/username_api.raml
@@ -0,0 +1,31 @@
+#%RAML 1.0
+
+title: username-availability API
+version: v1
+protocols: [ HTTPS ]
+baseUri: https://username-availability.herokuapp.com/
+
+types:
+  statusCode:
+    type: number
+    minimum: 100
+    maximum: 599
+    format: int64
+  Check:
+    type: object
+    properties:
+      avatar: null | string
+      possible: boolean
+      status: statusCode
+      url: string
+
+/check:
+  /{website}:
+    /{username}:
+      get:
+        description: Retrieve json for result of checking username
+        responses:
+          200:
+            body:
+              application/json:
+                type: Check