diff --git a/docs/api/swagger.md b/docs/api/swagger.md
index c31d6185a..ae9670b9f 100644
--- a/docs/api/swagger.md
+++ b/docs/api/swagger.md
@@ -1,9 +1,21 @@
-# API Documentation
+# Routes and Methods
 
 GoToSocial uses [go-swagger](https://github.com/go-swagger/go-swagger) to generate a V2 [OpenAPI specification](https://swagger.io/specification/v2/) document from code annotations.
 
-The resulting API documentation is rendered below, for quick reference.
+The resulting API documentation is rendered below. Please note that the doc is intended for reference only. You will not be able to use the built-in Authorize functionality in the below widget to actually connect to an instance or make API calls. Instead, you should use something like curl, Postman, or similar.
 
-If you'd like to do more with the spec, you can also view the [swagger.yaml](./swagger.yaml) directly, and then paste it into something like the [Swagger Editor](https://editor.swagger.io/) in order to autogenerate GoToSocial API clients in different languages, convert the doc to JSON or OpenAPI v3 specification, etc. See [here](https://swagger.io/tools/open-source/getting-started/) for more.
+Most of the GoToSocial API endpoints require a user-level OAuth token. For a guide on how to authenticate with the API using an OAuth token, see the [authentication doc](./authentication.md).
+
+!!! tip
+    If you'd like to do more with the spec, you can also view the [swagger.yaml](./swagger.yaml) directly, and then paste it into something like the [Swagger Editor](https://editor.swagger.io/). That way you can try autogenerating GoToSocial API clients in different languages (not supported, but fun), or convert the doc to JSON or OpenAPI v3 specification, etc. See [here](https://swagger.io/tools/open-source/getting-started/) for more.
+
+!!! info "Gotcha: uploading files"
+    When using an API endpoint that involves submitting a form to upload files (eg., the media attachments endpoints, or the emoji upload endpoint, etc), please note that `filename` is a required on the form field, due to the dependency that GoToSocial uses to parse forms, and some quirks in Go.
+    
+    See the following issues for more context:
+    
+    - [#1958](https://github.com/superseriousbusiness/gotosocial/issues/1958)
+    - [#1944](https://github.com/superseriousbusiness/gotosocial/issues/1944)
+    - [#2641](https://github.com/superseriousbusiness/gotosocial/issues/2641)
 
 <swagger-ui src="swagger.yaml"/>
diff --git a/docs/faq.md b/docs/faq.md
index 23403d363..8645efa5e 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -46,10 +46,6 @@ Take a look at the [list of open bugs](https://github.com/superseriousbusiness/g
 - account migration
 - shared block lists across servers
 
-## Warnings “authentication NOT PASSED for public key” in the log
-
-These warnings are caused by Mastodon forgetting to take query parameters into account when signing HTTP requests. Fixes on both Mastodon and GoToSocial sides are in the works, and other instance software is expected to follow.
-
 ## Will you support tables in Markdown?
 
 Not at the moment, as most clients handle them terribly.
diff --git a/mkdocs.yml b/mkdocs.yml
index b183add00..173b7aa03 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -123,8 +123,8 @@ nav:
       - "federation/index.md"
       - "federation/glossary.md"
       - "federation/federating_with_gotosocial.md"
-  - "API Documentation":
-      - "api/swagger.md"
+  - "Client API Docs":
       - "api/authentication.md"
+      - "api/swagger.md"
       - "api/ratelimiting.md"
       - "api/throttling.md"
diff --git a/web/source/settings/user/migration.tsx b/web/source/settings/user/migration.tsx
index ddfc71cdd..d0c5e3393 100644
--- a/web/source/settings/user/migration.tsx
+++ b/web/source/settings/user/migration.tsx
@@ -48,7 +48,7 @@ function UserMigrationForm({ data: profile }) {
 			<h2>Account Migration Settings</h2>
 			<div className="info">
 				<i className="fa fa-fw fa-exclamation-triangle" aria-hidden="true"></i>
-				<b>Moving your account to another instance, or moving an account from another instance to your account, isn't implemented yet! <a href="https://github.com/superseriousbusiness/gotosocial/issues/130" target="_blank" rel="noopener noreferrer">See here for progress</a>.</b>
+				<b>Moving your account to another instance, or moving an account from another instance to your account, isn't implemented yet! You will only be able to use the "alias" section of the below panel. <a href="https://github.com/superseriousbusiness/gotosocial/issues/130" target="_blank" rel="noopener noreferrer">See here for progress</a>.</b>
 			</div>
 			<p>
 				The following settings allow you to <strong>alias</strong> your account to another account