MultiPart Requests

Note: This feature is currently in alpha and the API may change. We would love to receive feedback.

A MultiPartBuilder is used to construct multipart (RFC 2388) payloads for requests. It enables adding raw data-sources or dynamic text content parts to build a multipart payload. Once all the parts have been added, pass the MultiPartBuilder into multi_part_payload field on the request.

var payload = new MultiPartBuilder();
payload.addField("firstname", "Smith");"/file-upload", { multi_part_payload: payload });

This example sends a POST request to /file-upload with Content-Type: multipart/form-data and a random boundary parameter. In the payload, there will be one part with a Content-Disposition header.


addField(fieldname, content) adds a new part to the MultiPartBuilder. Both fieldname and content can contain variables obtained via session.getVar(). The part will have a Content-Disposition header specifiying the fieldname.


addFields(options) is a helper function when to make adding multiple fields via addField() easier.

let payload = new MultiPartBuilder();
  'firstname': 'Mr',
  'lastname': 'Smith',
  'location': 'Cologne',


addFile(options) allows adding raw file fixtures to the multipart payload.

The options hash supports the following keys:

Parameter Required Description
name yes The form name field to be used for this part. Supports variables.
filename yes The filename that should be provided to the server for this part. Supports variables.
content_from_file yes The reference to the raw data source obtained via session.ds.getRawFile(). See data-sources.
content_type no The content-type for this file. Defaults to application/octet-stream. Supports variables.

Parts added via addPart() will have a Content-Disposition, Content-Type and Content-Transfer-Encoding header.

var payload = new MultiPartBuilder();
  'name': 'fileupload',
  'filename': 'userprofile.jpg',
  'content_from_file': session.ds.getRawFile("user-profile.jpg"),


The following example shows how you can use MultiPartBuilder inside your session to perform a POST request with a multipart payload.

var payload = new MultiPartBuilder();

// addField(fieldname, content) adds a single field to the multipart builder
payload.addField("firstname", "Smith");

// addFields(array) allows to adding multiple fields
  "lastname": "StormForger",
  "location": "Cologne",    

// addFile(options) adds a binary file. 
// name specifies the form field name.
// filename is the filename for the Content-Disposition header.
// content_type allows for specifiying the content-type header
// content_from_file specifies the raw datasource to use. See
  name: "upload_file",
  filename: "certificate.pem",
  content_from_file: session.ds.getRawFile("stormforger/multipart-example.txt"), 
  // content_type: "application/octet-stream" // octet is the default

// Finally pass in the MultiPartBuilder into the request with the multi_part_payload key."/data/test.json", {
  tag: "root",
  multi_part_payload: payload,
Icon Support Are you stuck? Or do you have any feedback? Get in touch with us – we are happy to help you.
Icon Schedule a demo Schedule a personal, customized demo. We'll show you around and introduce you to StormForger.
Icon Talk to a human To build and run reliable applications is complex – we know. Schedule a call and we’ll figure things out.