diff --git a/lib/pleroma/web/api_spec/operations/custom_emoji_operation.ex b/lib/pleroma/web/api_spec/operations/custom_emoji_operation.ex
new file mode 100644
index 000000000..cf2215823
--- /dev/null
+++ b/lib/pleroma/web/api_spec/operations/custom_emoji_operation.ex
@@ -0,0 +1,25 @@
+# Pleroma: A lightweight social networking server
+# Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+defmodule Pleroma.Web.ApiSpec.CustomEmojiOperation do
+  alias OpenApiSpex.Operation
+  alias Pleroma.Web.ApiSpec.Schemas.CustomEmojisResponse
+
+  def open_api_operation(action) do
+    operation = String.to_existing_atom("#{action}_operation")
+    apply(__MODULE__, operation, [])
+  end
+
+  def index_operation do
+    %Operation{
+      tags: ["custom_emojis"],
+      summary: "List custom custom emojis",
+      description: "Returns custom emojis that are available on the server.",
+      operationId: "CustomEmojiController.index",
+      responses: %{
+        200 => Operation.response("Custom Emojis", "application/json", CustomEmojisResponse)
+      }
+    }
+  end
+end
diff --git a/lib/pleroma/web/api_spec/schemas/custom_emoji.ex b/lib/pleroma/web/api_spec/schemas/custom_emoji.ex
new file mode 100644
index 000000000..5531b2081
--- /dev/null
+++ b/lib/pleroma/web/api_spec/schemas/custom_emoji.ex
@@ -0,0 +1,30 @@
+# Pleroma: A lightweight social networking server
+# Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+defmodule Pleroma.Web.ApiSpec.Schemas.CustomEmoji do
+  alias OpenApiSpex.Schema
+
+  require OpenApiSpex
+
+  OpenApiSpex.schema(%{
+    title: "CustomEmoji",
+    description: "Response schema for an CustomEmoji",
+    type: :object,
+    properties: %{
+      shortcode: %Schema{type: :string},
+      url: %Schema{type: :string},
+      static_url: %Schema{type: :string},
+      visible_in_picker: %Schema{type: :boolean},
+      category: %Schema{type: :string},
+      tags: %Schema{type: :array}
+    },
+    example: %{
+      "shortcode" => "aaaa",
+      "url" => "https://files.mastodon.social/custom_emojis/images/000/007/118/original/aaaa.png",
+      "static_url" =>
+        "https://files.mastodon.social/custom_emojis/images/000/007/118/static/aaaa.png",
+      "visible_in_picker" => true
+    }
+  })
+end
diff --git a/lib/pleroma/web/api_spec/schemas/custom_emojis_response.ex b/lib/pleroma/web/api_spec/schemas/custom_emojis_response.ex
new file mode 100644
index 000000000..01582a63d
--- /dev/null
+++ b/lib/pleroma/web/api_spec/schemas/custom_emojis_response.ex
@@ -0,0 +1,42 @@
+# Pleroma: A lightweight social networking server
+# Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+defmodule Pleroma.Web.ApiSpec.Schemas.CustomEmojisResponse do
+  alias Pleroma.Web.ApiSpec.Schemas.CustomEmoji
+
+  require OpenApiSpex
+
+  OpenApiSpex.schema(%{
+    title: "CustomEmojisResponse",
+    description: "Response schema for custom emojis",
+    type: :array,
+    items: CustomEmoji,
+    example: [
+      %{
+        "category" => "Fun",
+        "shortcode" => "blank",
+        "static_url" => "https://lain.com/emoji/blank.png",
+        "tags" => ["Fun"],
+        "url" => "https://lain.com/emoji/blank.png",
+        "visible_in_picker" => true
+      },
+      %{
+        "category" => "Gif,Fun",
+        "shortcode" => "firefox",
+        "static_url" => "https://lain.com/emoji/Firefox.gif",
+        "tags" => ["Gif", "Fun"],
+        "url" => "https://lain.com/emoji/Firefox.gif",
+        "visible_in_picker" => true
+      },
+      %{
+        "category" => "pack:mixed",
+        "shortcode" => "sadcat",
+        "static_url" => "https://lain.com/emoji/mixed/sadcat.png",
+        "tags" => ["pack:mixed"],
+        "url" => "https://lain.com/emoji/mixed/sadcat.png",
+        "visible_in_picker" => true
+      }
+    ]
+  })
+end
diff --git a/lib/pleroma/web/mastodon_api/controllers/custom_emoji_controller.ex b/lib/pleroma/web/mastodon_api/controllers/custom_emoji_controller.ex
index d82de1db5..3bfebef8b 100644
--- a/lib/pleroma/web/mastodon_api/controllers/custom_emoji_controller.ex
+++ b/lib/pleroma/web/mastodon_api/controllers/custom_emoji_controller.ex
@@ -5,6 +5,10 @@
 defmodule Pleroma.Web.MastodonAPI.CustomEmojiController do
   use Pleroma.Web, :controller
 
+  plug(OpenApiSpex.Plug.CastAndValidate)
+
+  defdelegate open_api_operation(action), to: Pleroma.Web.ApiSpec.CustomEmojiOperation
+
   def index(conn, _params) do
     render(conn, "index.json", custom_emojis: Pleroma.Emoji.get_all())
   end
diff --git a/test/web/mastodon_api/controllers/custom_emoji_controller_test.exs b/test/web/mastodon_api/controllers/custom_emoji_controller_test.exs
index 6567a0667..0b2ffa470 100644
--- a/test/web/mastodon_api/controllers/custom_emoji_controller_test.exs
+++ b/test/web/mastodon_api/controllers/custom_emoji_controller_test.exs
@@ -4,13 +4,18 @@
 
 defmodule Pleroma.Web.MastodonAPI.CustomEmojiControllerTest do
   use Pleroma.Web.ConnCase, async: true
+  alias Pleroma.Web.ApiSpec
+  alias Pleroma.Web.ApiSpec.Schemas.CustomEmoji
+  alias Pleroma.Web.ApiSpec.Schemas.CustomEmojisResponse
+  import OpenApiSpex.TestAssertions
 
   test "with tags", %{conn: conn} do
-    [emoji | _body] =
-      conn
-      |> get("/api/v1/custom_emojis")
-      |> json_response(200)
+    assert resp =
+             conn
+             |> get("/api/v1/custom_emojis")
+             |> json_response(200)
 
+    assert [emoji | _body] = resp
     assert Map.has_key?(emoji, "shortcode")
     assert Map.has_key?(emoji, "static_url")
     assert Map.has_key?(emoji, "tags")
@@ -18,5 +23,19 @@ test "with tags", %{conn: conn} do
     assert Map.has_key?(emoji, "category")
     assert Map.has_key?(emoji, "url")
     assert Map.has_key?(emoji, "visible_in_picker")
+    assert_schema(resp, "CustomEmojisResponse", ApiSpec.spec())
+    assert_schema(emoji, "CustomEmoji", ApiSpec.spec())
+  end
+
+  test "CustomEmoji example matches schema" do
+    api_spec = ApiSpec.spec()
+    schema = CustomEmoji.schema()
+    assert_schema(schema.example, "CustomEmoji", api_spec)
+  end
+
+  test "CustomEmojisResponse example matches schema" do
+    api_spec = ApiSpec.spec()
+    schema = CustomEmojisResponse.schema()
+    assert_schema(schema.example, "CustomEmojisResponse", api_spec)
   end
 end