{}jsonbin.io

Root

https://api.jsonbin.io/v3 Copy

Route

/b Copy

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-Access-Key	<ACCESS_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-Access-Key Required

You can now create bins with X-Access-Key header too. Refer to the FAQs for more information on X-Access-Key. Make sure you've granted Bins Create Access Permission to the Access Key you'll be using. You can create Access Keys on 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

Copycurl -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

Copylet 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"}');

Copyimport 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)

Copyrequire '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