diff --git a/README.md b/README.md
index 69f7e9b..d7be0a8 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,17 @@
 # backupd
+
+a dead simple backup server
+
+## usage
+
+### as a hoster
+
+to get started, `git clone` this repo to a permanent location, and create `docker-compose.yml` and `config.json` from their `.example` files. modify those to your likind and `docker-compose up -d` it.
+
+to create a new client, add an entry to `config.json` like in example. don't forget to put their password's `SHA256` sum in the `keySha256Sum` field.
+
+### as a client
+
+first step is get your key from the hoster, or make a client yourself if you are the hoster.
+
+then, see [the API reference](./openapi.yml)
diff --git a/openapi.yml b/openapi.yml
new file mode 100644
index 0000000..74af5de
--- /dev/null
+++ b/openapi.yml
@@ -0,0 +1,101 @@
+openapi: 3.0.0
+info:
+    title: Backup server API
+    description: |
+        The backup server API reference
+    version: 0.0.1 GPL-3.0-only
+tags:
+    - name: General
+paths:
+    /upload:
+        post:
+            description: Upload a file
+            summary: Upload a file
+            tags: [General]
+            responses:
+                '200':
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    status:
+                                        type: string
+                                        example: ok
+                                    name:
+                                        type: string
+                                        example: sample-filename
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                data:
+                                    type: string
+                                    example: base64 encoded file
+                                name:
+                                    type: string
+                                    example: sample-filename
+    /get/{name}:
+        get:
+            description: Get a file
+            summary: Get a file
+            tags: [General]
+            parameters:
+                - in: path
+                  name: name
+                  schema: { type: string }
+                  required: true
+            responses:
+                200:
+                    description: |
+                        OK
+
+                        The returned body is the file
+                    content:
+                        application/octet-stream:
+                            example: ''
+    /list:
+        get:
+            description: List all files owned by you
+            summary: List all files
+            tags: [General]
+            responses:
+                200:
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items:
+                                    type: string
+    /{name}:
+        delete:
+            description: Delete a file
+            summary: Deleete a file
+            tags: [General]
+            parameters:
+                - in: path
+                  name: name
+                  schema: { type: string }
+                  required: true
+            responses:
+                200:
+                    description: OK
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    status:
+                                        type: string
+                                        example: ok
+components:
+    securitySchemes:
+        key:
+            type: http
+            scheme: bearer
+security:
+    - key: []