Create XL Bins API

If you are looking to Store a Large JSON file, then you need to use the Create XL Bins API.

This API also allows you to Add a Name to your Bin, Creating large Public or a Private JSON record.

INFO Consider using Create Bins API if you wish to create files under 1MB.

IMPORTANT XL Bins API is an Early Access Feature. It may change drastically over time or may get discontinued in the future. We would not recommend you to use this feature on Production until it graduates to a stable release in the future.




Request Type


Request Headers

Below are the list of Accepted Request Headers if you are trying to Create a JSON record.

Request Header Value Required
Content-Type multipart/form-data Yes
X-Master-Key <API_KEY> Yes
X-Bin-Private <true / false> No
X-Bin-Name <BIN_NAME> No
Content-Type Required

Set the Content-Type header to multipart/form-data. This needs to be passed with every POST request you make on the Create XL Bins Route. Failing to pass this in the Header will result in an error.

X-Master-Key Required

X-Master-Key is nothing but your Core API Access Key. You will need this Key to access mostly any API end-point on JSONBin. You could find the key on the API Keys page.

X-Bin-Private Optionaldefault: true

When creating a XL JSON Bin, you can decide if you wish to set the visibility to Private or Public. By default, the bin is created as a private bin. If you wish to create a Public Bin, which can be Read by anyone who has the Bin Id, then pass the value of false.

X-Bin-Name Optional

Creating an XL JSON Bin will generate a Random Id which will be used to take any action like Read, Update and so on. Since the Id is not enough to identify the bins, you can use X-Bin-Name header to set the Name for the Bin. Note that this name is purely for identification purpose, and as of now, you cannot use this name to take any action on the respective Bin.

The Bin Name you can set is of a Limited character. Any name between 1-128 characters is allowed.

Request Body

Below are the list of Accepted Request Body Parameters if you are trying to Create an XL JSON record.

Request Body Name Value Required
xlbin <YOUR_FILE> Yes

Code Samples

  • cURL
curl -X POST \
  -H "X-Bin-Name: BIN_NAME" \
  -H "X-Master-Key: <YOUR_API_KEY>" \
  -F "xlbin=@/<YOUR_FILE_PATH>;type=application/json" \

Request Response

Success Status Code: 200
  "metadata": {
    "id":"<Bin Id>",
    "createdAt":"<Date & Time>",
    "private": <true/false>,
    "name": "<Bin Name>"
Error Status Code: 400, 401, 403, 404
  "message": "<Error Message>"

For more information on the error codes & errors you might possibly encounter, refer to the below section.

Error Reference

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 413 Content Too Large
X-Bin-Name cannot be blank or over 128 characters

You'll face this error if you are having a bin name longer than 128 characters. To fix this, please name your bin under 128 characters.

No files were uploaded.

You need to upload a JSON file to create an XL Bin record. Make sure you also pass xlbin field as a name parameter to your JSON file.

You can upload a single JSON file only

Only one JSON file can be uploaded. You'll encounter this error if you are trying to upload more than one JSON file to create an XL Bin record.

XL bin parameter was not passed

Make sure you pass xlbin parameter as the name field for your JSON file uploaded.

Invalid file found. Only JSON files are allowed

Above error will be encountered if you are trying to upload any file other than JSON.

File sizes under 1mb are not allowed for XL bins. Consider creating a simple bin instead.

You can create normal Bins using the Bins API if the file size is under 1mb. You could only use XL Bins if the file size is above 1mb.

JSON file has errors. Fix and retry.

JSON file you uploaded has malformed JSON and is not valid. Make sure the JSON is valid and try again.

You need to pass X-Master-Key in the header to create an XL bin

You'll encounter this error if you are not passing the X-Master-Key in the header which is required to authenticate your request while creating XL bins. In-order to fix this, pass the X-Master-Key header with a value of the API Key which you can find on the API Keys page.

Invalid X-Master-Key provided

The X-Master-Key you have passed is invalid. Please verify the X-Master-Key and try again.

XL Bins are not available for the Free users. Upgrade to Pro plan to avail this feature

You could split your JSON files into multiple smaller files or upgrade your Account to Pro instead.

Requests exhausted. Buy additional requests at

You'll encounter this error if you've consumed all the available requests. You can purchase additional requests.

XL Bins is an Early Access Feature. You need to enable Early Access to create XL Bins. For more information about Early Access, please visit the page.

XL Bins is an eary access feature. Hence, you need to enable Early Access from your Account page to avail the feature. Note, that you would also need a paid account as the above is not available for free users.

File size exceeded. File sizes above 10mb are not allowed for XL bins.

You cannot upload a JSON file above 10mb.

Create a Free Account

Create an Account View Pricing