Bin Name API

Creating a Bin is easy and fast, but it often gets tedious to search for the right bin if you have not set the name for one. Using the Update Bin Name API, you can set or Update the Name of the Bin.




Request Type


Request Headers

Below are the list of Accepted Request Headers if you are trying to Set or Update the name of your JSON record.

Request Header Value Required
X-Master-Key <API_KEY> Yes
X-Bin-Name <BIN_NAME> Yes
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-Name Required

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 or Update 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.

Code Samples

  • cURL
  • JavaScript (ES6)
  • Python 3
  • Ruby
curl -v\
-H "X-Master-key: <API_KEY>" \
-H "X-Bin-Name: TestName" \
--request PUT \
--data '{}' \<BIN_ID>/meta/name
let req = new XMLHttpRequest();

req.onreadystatechange = () => {
  if (req.readyState == XMLHttpRequest.DONE) {
};"PUT", "<BIN_ID>/meta/name", true);
req.setRequestHeader("X-Bin-Name", "TestName");
req.setRequestHeader("X-Master-Key", "<API_KEY>");
import requests
url = '<BIN_ID>/meta/name'
headers = {
  'X-Bin-Name': 'TestName',
  'X-Master-Key': '<YOUR_API_KEY>'
data = {}

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

uri = URI("<BIN_ID>/meta/name")
res = Net::HTTP.start(, uri.port, use_ssl: true) do |http|
  req =
  req['X-Bin-Name'] = 'TestName'
  req['X-Master-Key'] = '<YOUR_API_KEY>'

  req.body = {}.to_json

puts res.body

Request Response

Success Status Code: 200
  "record": "RECORD_ID",
  "metadata": {
    "name": "YOUR_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
  • 404 Not Found
X-Bin-Name cannot be blank or over 128 characters

You will encounter the above error if your Bin Name is blank or it is set above 128 characters. In-order to fix this, you need to set the bin name between 1-128 characters.

You need to pass X-Bin-Name header to Update the Bin Name

You need to pass the X-Bin-Name header to Set or Update the name of the Bin.

Invalid Bin Id provided

You'll encounter this error if the Bin Id you are trying to access is invalid. Hence, ensure that the Bin Id you are passing is valid.

You need to pass X-Master-Key in the header to update a name of the bin

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.

Invalid X-Master-Key provided or the bin does not belong to your account

You could encounter this error if the X-Master-Key you've passed is invalid, or the Bin you are trying to access does exists but does not belong to your account.

Requests exhausted. Buy additional requests at

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

Bin not found

Verify the Bin Id and ensure that the Bin belongs to your account.

Create a Free Account

Create an Account View Pricing