diff --git a/README.md b/README.md
index 7f4d693..41520c8 100644
--- a/README.md
+++ b/README.md
@@ -39,31 +39,4 @@ python -m test
 
 ## REST API
 
-* All requests via HTTP GET except where noted.
-* Data returned as JSON
-* All responses include `status` (an HTTP standard RFC 2616 response code) and `message` populated on error.
-
-/ - returns basic info
-
-/status - returns uptime and free space
-
-### /trust (POST) - set or update single trust value
-    Either value or delta must be set.
-
-    Parameters
-        source - string
-        dest - string
-        value - set trust value from source to dest, float in range (-100.0, 100.0) 
-        delta - amount to increment or decrement trust value, float in range (-200.0, 200)
-
-### /score - return score from source to dest
-    Parameters
-        source - string
-        dest - string
-
-    Returns
-        trusted - boolean
-        
-### /rescore - recalculate scores
-    Parameters
-        (none)
+The API is defined in openapi-spec.yaml
diff --git a/openapi-spec.yaml b/openapi-spec.yaml
new file mode 100644
index 0000000..464f5ac
--- /dev/null
+++ b/openapi-spec.yaml
@@ -0,0 +1,89 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Web of Trust API
+  description: Providing API access to update trust scores,  retrieve trusted state and recalculate scoring.
+
+servers:
+  - url: http://localhost:20202
+
+paths:
+  /trust:
+    post:
+      description: Set or update single trust value
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - source
+                - target
+              properties:
+                source:
+                  description: Giver of trust
+                  type: string
+                target:
+                  description: Recipient of trust
+                  type: string
+                value:
+                  type: number
+                delta:
+                  type: number
+      responses:
+        '200':
+          description: Success set or updated a trust value
+  /score:
+    get:
+      description: Set or update single trust value
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - source
+                - target
+              properties:
+                source:
+                  description: Giver of trust
+                  type: string
+                target:
+                  description: Recipient of trust
+                  type: string
+      responses:
+        '200':
+          description: Successfully retrieved
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  trusted:
+                    type: boolean
+        '400':
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:   
+                  message:
+                    type: string
+  /rescore:
+    get:
+      description: Recalculate scores
+      responses:
+        '200':
+          description: Successfully retrieved
+        '400':
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:   
+                  message:
+                    type: string
diff --git a/server.py b/server.py
index 8107ccf..8f30c30 100644
--- a/server.py
+++ b/server.py
@@ -93,12 +93,13 @@ def put():
     try:
         body = request.data.decode('utf-8')
         in_obj = json.loads(body)
+        s = in_obj['source']          # source user's id
+        t = in_obj['target']          # target user's id
+        v = in_obj['value']           # integer value for rating
     except:
-        return ("JSON Decode failed", 400, {'Content-Type':'text/plain'})
-
-    s = in_obj['source']          # source user's id
-    t = in_obj['target']          # target user's id
-    v = in_obj['value']           # integer value for rating
+        body = '{"message": "JSON Decode failed"}'
+        return (body, 400, {'Content-length': 0,
+                            'Content-Type':'text/plain'})
 
     trust = db.session.query(Trust).filter(and_(Trust.user_id == s, Trust.user_id2 == t)).first()
     if trust is None:
@@ -109,13 +110,9 @@ def put():
         trust.value = v
         db.session.commit()
     
-    body = json.dumps({'result': 'success'})
-    code = 201
-    
-    return (body, code, {'Content-length': len(body),
-                         'Content-type': 'application/json',
-                        }
-    )
+    return ('', 200, {'Content-length': 0,
+                      'Content-type': 'application/json',
+                     })
 
 @app.route('/delete', methods=['POST'])
 def delete():