Create Bins API

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

This API also allows you to Add a Name your Bin, Create Public or a Private JSON record, and along with this, you can also add it to a specific Collection.

Root

https://api.jsonbin.io/v3 

Route

/b 

Request Type

POST

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 application/json Yes
X-Master-Key <API_KEY> Yes
X-Bin-Private <true / false> No
X-Bin-Name <BIN_NAME> No
X-Collection-Id <COLLECTION_ID> No
Content-Type Required

Set the Content-Type header to application/json. This needs to be passed with every POST request you make on the Create 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 JSON record, you can decide if you wish to set the visibility to Private or Public. By default, the record is created as a private record. If you wish to create a Public record, which can be Read and Updated by anyone who has the Bin Id, then pass the value of false.

Info When someone tries to Update a Public record, the Version Control cannot be disabled. This is by design as it prevents you from losing the Data of your Public record, if someone tries to update it. For more information, refer to the Update Bins API.

X-Bin-Name Optional

Creating a JSON record 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 records, 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.

X-Collection-Id Optional

You can add a record to a specific Collection. This is helpful when you want to group these records in a specific category, and also, you can validate these records against a JSON Schema.

You can pass the above header along with the Collection Id which you could retrieve once you Create a Collection.

Code Samples

  • cURL
  • JavaScript (ES6)
  • Python 3
  • Ruby
curl -v\
  -H "Content-Type: application/json" \
  -H "X-Master-key: <YOUR_API_KEY>" \
  --request POST \
  --data '{"sample": "Hello World"}' \
    https://api.jsonbin.io/v3/b
let req = new XMLHttpRequest();

req.onreadystatechange = () => {
  if (req.readyState == XMLHttpRequest.DONE) {
    console.log(req.responseText);
  }
};
  
req.open("POST", "https://api.jsonbin.io/v3/b", true);
req.setRequestHeader("Content-Type", "application/json");
req.setRequestHeader("X-Master-Key", "<YOUR_API_KEY>");
req.send('{"sample": "Hello World"}');
import requests
url = 'https://api.jsonbin.io/v3/b'
headers = {
  'Content-Type': 'application/json',
  'X-Master-Key': '<YOUR_API_KEY>'
}
data = {"sample": "Hello World"}

req = requests.post(url, json=data, headers=headers)
print(req.text)
require 'net/http'
require 'json'

uri = URI("https://api.jsonbin.io/v3/b")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  req = Net::HTTP::Post.new(uri)
  req['Content-Type'] = 'application/json'
  req['X-Master-Key'] = '<YOUR_API_KEY>'

  req.body = {"sample": "Hello World"}.to_json
  http.request(req)
end

puts res.body

Request Response

Success Status Code: 200
{
  "record": {
    "sample": "Hello World"
  },
  "metadata": {
    "id": "<Bin Id>",
    "createdAt": "<Date & Time>",
    "private": <true or false>
  }
}
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
You need to pass Content-Type set to application/json

You'll encounter this error if you are not passing the Content-Type header. Hence, pass the Content-Type header with a value of application/json.

Bin cannot be blank

To solve this issue, you need to pass some JSON in the request Body

X-Bin-Name cannot be blank or over 128 characters

As the error suggests, 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.

Invalid X-Collection-Id provided

You'll encounter this error when you've passed X-Collection-Id header but either the Collection Id was invalid. Verify the Collection Id again and pass the correct Id in the header.

Collection not found or the Collection does not belong to the X-Master-Key provided

Check if you are passing the right Collection Id or the Id is valid but it does not belong to your account.

Schema Doc Validation Mismatch: key:val

You'll encounter this error only when you are trying to Create a record in a specific collection which has a Schema Validation doc attached to it. If your JSON does not match the SchemaDoc, it will result in the above error.

You need to pass X-Master-Key in the header

You'll encounter this error if you are not passing the X-Master-Key header which is required to authenticate your request while creating 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.

Free users cannot create a record over 500kb. Upgrade to Pro plan https://jsonbin.io/pricing to create records upto 1mb

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

Requests exhausted. Buy additional requests at https://jsonbin.io/pricing

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

Create a Free Account

Create an Account View Pricing