diff --git a/templates/zerver/api/add-emoji-reaction.md b/templates/zerver/api/add-emoji-reaction.md
new file mode 100644
index 0000000000..7ce7988e35
--- /dev/null
+++ b/templates/zerver/api/add-emoji-reaction.md
@@ -0,0 +1,32 @@
+# Add an emoji reaction
+
+Add an [emoji reaction](/help/emoji-reactions) to a message.
+
+`POST {{ api_url }}/v1/messages/{message_id}/reactions`
+
+
+## Usage examples
+
+{start_tabs}
+{tab|python}
+
+{generate_code_example(python)|/messages/{message_id}/reactions:post|example}
+
+{tab|curl}
+
+{generate_code_example(curl, exclude=["emoji_code","reaction_type"])|/messages/{message_id}/reactions:post|example}
+
+{end_tabs}
+
+## Arguments
+
+
+{generate_api_arguments_table|zulip.yaml|/messages/{message_id}/reactions:post}
+
+## Response
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/messages/{message_id}/reactions:post|fixture(200)}
diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md
index 18443e5a26..e30cba2e60 100644
--- a/templates/zerver/help/include/rest-endpoints.md
+++ b/templates/zerver/help/include/rest-endpoints.md
@@ -4,6 +4,7 @@
 * [Get a raw message](/api/get-raw-message)
 * [Send a message](/api/send-message)
 * [Update a message](/api/update-message)
+* [Add an emoji reaction](/api/add-emoji-reaction)
 * [Render a message](/api/render-message)
 * [Upload a file](/api/upload-file)
 * [Delete a message](/api/delete-message)
diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.py
index 6e985ada32..867fc934b7 100644
--- a/zerver/openapi/python_examples.py
+++ b/zerver/openapi/python_examples.py
@@ -698,25 +698,26 @@ def send_message(client):
 
     return message_id
 
+@openapi_test_function("/messages/{message_id}/reactions:post")
 def add_reaction(client, message_id):
     # type: (Client, int) -> None
+    # {code_example|start}
+    # Add an emoji reaction
     request = {
         'message_id': str(message_id),
-        'emoji_name': 'joy',
-        'emoji_code': '1f602',
-        'emoji_type': 'unicode_emoji'
+        'emoji_name': 'octopus',
     }
-    result = client.add_reaction(request)
 
-    assert result['result'] == 'success'
+    result = client.add_reaction(request)
+    # {code_example|end}
+    validate_against_openapi_schema(result, '/messages/{message_id}/reactions', 'post', '200')
 
 @openapi_test_function("/messages/{message_id}/reactions:delete")
 def remove_reaction(client, message_id):
     # type: (Client, int) -> None
     request = {
         'message_id': str(message_id),
-        'emoji_name': 'joy',
-        'emoji_code': '1f602',
+        'emoji_name': 'octopus',
         'reaction_type': 'unicode_emoji'
     }
 
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index 529bfa16f2..97d53e1c7d 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -845,17 +845,26 @@ paths:
                      you want, and note that emoji's text name.
         schema:
           type: string
-        example: '**:slight smile:**'
+        example: 'octopus'
         required: true
       - name: emoji_code
         in: query
         description: |
-                     An encoded version of the unicode codepoint. Used only
-                     in rare corner cases to consolidate identical reactions
-                     to the same emoji name.
+                     An encoded version of the unicode codepoint.  For
+                     most clients, you won't need this; it's used to
+                     handle a rare corner case when upvoting a unicode
+                     emoji reaction added previously by another user.
+
+                     If the existing reaction was added when the Zulip
+                     server was using a previous version of the emoji
+                     data mapping from codepoints to human-readable
+                     names, sending the `emoji_code` in the data for
+                     the original reaction allows the Zulip server to
+                     correctly consider your upvote as an upvote
+                     rather than a reaction with a "diffenent" emoji.
         schema:
           type: string
-        example: '**foo**'
+        example: '1f419'
         required: false
       - name: reaction_type
         in: query
@@ -864,7 +873,7 @@ paths:
                      set `reaction_type` to `realm_emoji`.
         schema:
           type: string
-        example: '**realm_emoji**'
+        example: 'unicode_emoji'
         required: false
       responses:
         '200':
@@ -874,16 +883,26 @@ paths:
               schema:
                 allOf:
                 - $ref: '#/components/schemas/JsonSuccess'
-                - properties:
-                    rendered:
-                      type: string
-                      description: The rendered HTML.
+                - example:
+                      {
+                          "result": "success",
+                          "msg": ""
+                      }
+
+        '400':
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/CodedError'
                 - example:
                     {
-                        "msg": "",
-                        "rendered": "<p><strong>foo</strong></p>",
-                        "result": "success"
+                        "result": "error",
+                        "msg": "Invalid emoji code",
+                        "code": "BAD_REQUEST"
                     }
+
     delete:
       description: Delete an emoji reaction from a message.
       parameters: