From b662a33081eaf894acf389721d0731cbbbf80f44 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Mon, 4 Nov 2019 15:47:25 -0700
Subject: [PATCH] Recommend that clients don't preview URLs in encrypted rooms

Any stronger of a recommendation would probably require a MSC due to the behaviour change.

Fixes https://github.com/matrix-org/matrix-doc/issues/2120
---
 api/client-server/content-repo.yaml                       | 8 ++++++++
 changelogs/client_server/newsfragments/2343.clarification | 1 +
 2 files changed, 9 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/2343.clarification

diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml
index a9a0c2f69..577e63b89 100644
--- a/api/client-server/content-repo.yaml
+++ b/api/client-server/content-repo.yaml
@@ -340,6 +340,14 @@ paths:
   "/preview_url":
     get:
       summary: "Get information about a URL for a client"
+      description: |-
+        Get information about a URL for the client. Typically this is called when a
+        client sees a URL in a message and wants to render a preview for the user.
+
+        .. Note::
+          Clients should consider avoiding this endpoint for URLs posted in encrypted
+          rooms.
+
       operationId: getUrlPreview
       produces: ["application/json"]
       security:
diff --git a/changelogs/client_server/newsfragments/2343.clarification b/changelogs/client_server/newsfragments/2343.clarification
new file mode 100644
index 000000000..5b16858b8
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2343.clarification
@@ -0,0 +1 @@
+Clarify that clients should consider not requesting URL previews in encrypted rooms.