diff --git a/api/application-service/transactions.yaml b/api/application-service/transactions.yaml
index 09f152765..a557325c5 100644
--- a/api/application-service/transactions.yaml
+++ b/api/application-service/transactions.yaml
@@ -50,7 +50,7 @@ paths:
           x-example: "35"
         - in: body
           name: body
-          description: A list of events.
+          description: Transaction information
           schema:
             type: object
             example: {
@@ -59,7 +59,6 @@ paths:
                 {"$ref": "../../event-schemas/examples/m.room.message$m.text"}
               ]
             }
-            description: Transaction information
             properties:
               events:
                 type: array
diff --git a/api/client-server/device_management.yaml b/api/client-server/device_management.yaml
index 094084bf1..c42ebbd7c 100644
--- a/api/client-server/device_management.yaml
+++ b/api/client-server/device_management.yaml
@@ -119,9 +119,9 @@ paths:
               display_name:
                 type: string
                 description: |-
-                    The new display name for this device. If not given, the
-                    display name is unchanged.
-                example: My other phone
+                  The new display name for this device. If not given, the
+                  display name is unchanged.
+            example: { "display_name": "My other phone" }
       responses:
         200:
           description: The device was successfully updated.
diff --git a/api/client-server/kicking.yaml b/api/client-server/kicking.yaml
index 7fbee38bd..fd3f16986 100644
--- a/api/client-server/kicking.yaml
+++ b/api/client-server/kicking.yaml
@@ -77,7 +77,8 @@ paths:
             type: object
         403:
           description: |-
-            You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+            You do not have permission to kick the user from the room. A meaningful ``errcode`` and
+            description error text will be returned. Example reasons for rejections are:
 
             - The kicker is not currently in the room.
             - The kickee is not currently in the room.
diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml
index 874ac59b9..b3a8bb029 100644
--- a/api/client-server/presence.yaml
+++ b/api/client-server/presence.yaml
@@ -62,7 +62,7 @@ paths:
                 description: The new presence state.
               status_msg:
                 type: string
-                description: "The status message to attach to this state."
+                description: The status message to attach to this state.
             required: ["presence"]
       responses:
         200:
diff --git a/api/client-server/profile.yaml b/api/client-server/profile.yaml
index c8dc40563..db998e6c7 100644
--- a/api/client-server/profile.yaml
+++ b/api/client-server/profile.yaml
@@ -45,7 +45,7 @@ paths:
           x-example: "@alice:example.com"
         - in: body
           name: displayName
-          description: The display name info.
+          description: The new display name information.
           required: true
           schema:
             type: object
@@ -119,7 +119,7 @@ paths:
           x-example: "@alice:example.com"
         - in: body
           name: avatar_url
-          description: The avatar url info.
+          description: The new avatar information.
           required: true
           schema:
             type: object
diff --git a/api/client-server/room_upgrades.yaml b/api/client-server/room_upgrades.yaml
index 3aaaadcb4..97ef611e5 100644
--- a/api/client-server/room_upgrades.yaml
+++ b/api/client-server/room_upgrades.yaml
@@ -45,7 +45,6 @@ paths:
         - in: body
           name: body
           required: true
-          description: The request body
           schema:
             type: object
             properties:
diff --git a/api/server-server/public_rooms.yaml b/api/server-server/public_rooms.yaml
index 0216f0c31..5324eac39 100644
--- a/api/server-server/public_rooms.yaml
+++ b/api/server-server/public_rooms.yaml
@@ -86,7 +86,7 @@ paths:
           name: body
           required: true
           description: |-
-            Options for which rooms to return.
+            Options for which rooms to return, or empty object to use defaults.
           schema:
             type: object
             properties: