diff --git a/username_api.raml b/username_api.raml
new file mode 100644
index 0000000..318c492
--- /dev/null
+++ b/username_api.raml
@@ -0,0 +1,36 @@
+#%RAML 1.0
+
+title: username-availability API
+version: v1
+protocols: [ HTTPS ]
+baseUri: https://username-availability.herokuapp.com
+
+types:
+  Check:
+    type: object
+    properties:
+      avatar?: null | string
+      possible: boolean
+      profile?: string
+      status?: number
+      url: string
+      usable: boolean
+
+/check:
+  /{website}:
+    uriParameters:
+      website:
+        type: string
+        required: true
+    /{username}:
+      uriParameters:
+        username:
+          type: string
+          required: true
+      get:
+        description: Retrieve json for result of checking username
+        responses:
+          200:
+            body:
+              application/json:
+                type: Check