1 files changed, 50 insertions, 0 deletions
diff --git a/docs/requests/multipart.rst b/docs/requests/multipart.rst
new file mode 100644
index 0000000..ac921fc
--- /dev/null
+++ b/docs/requests/multipart.rst
@@ -0,0 +1,50 @@
+.. _multipart:
+
+Multipart requests
+==================
+
+To set a multipart body on a request, the ``multipartBody`` method should be used (instead of ``body``). Each body part is represented as an instance of ``Multipart``, which can be conveniently constructed using ``multipart`` methods coming from the ``com.softwaremill.sttp`` package.
+
+A single part of a multipart request consist of a mandatory name and a payload of type:
+
+* ``String``
+* ``Array[Byte]``
+* ``ByteBuffer``
+* ``InputStream``
+* ``File``
+* ``Path``
+* ``Map[String, String]``
+* ``Seq[(String, String)]``
+
+The content type of each part is by default the same as when setting simple bodies: ``text/plain`` for parts of type ``String``, ``application/x-www-form-urlencoded`` for parts of key-value pairs (form data) and ``application/octet-stream`` otherwise (for binary data). 
+
+The parts can be specified using either a ``Seq[Multipart]`` or by using multiple arguments::
+
+  def multipartBody(ps: Seq[Multipart])
+  def multipartBody(p1: Multipart, ps: Multipart*)
+
+For example::
+
+  sttp.multipartBody(
+    multipart("text_part", "data1"),
+    multipart("file_part", someFile), // someFile: File
+    multipart("form_part", Map("x" -> "10", "y" -> "yes"))
+  )
+
+Customising part meta-data
+--------------------------
+
+For each part, an optional filename can be specified, as well as a custom content type and additional headers. The following methods are available on ``Multipart`` instances::
+
+  case class Multipart {
+    def fileName(v: String): Multipart 
+    def contentType(v: String): Multipart
+    def header(k: String, v: String): Multipart
+  }
+
+For example::
+
+  sttp.multipartBody(
+    multipart("logo", logoFile).fileName("logo.jpg").contentType("image/jpg"),
+    multipart("text", docFile).fileName("text.doc")
+  )