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.
Root
https://api.jsonbin.io/v3 Route
/xl/b Request Type
POSTRequest 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 -X POST \
-H "X-Bin-Name: BIN_NAME" \
-H "X-Master-Key: <YOUR_API_KEY>" \
-F "xlbin=@/<YOUR_FILE_PATH>;type=application/json" \
https://api.jsonbin.io/v3/xl/bRequest 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
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.