{}jsonbin.io

Read Bins API

The bins you store on JSONBin.io, either Uncategorized or in a Collection can be Read using the Read Bins API.

The API allows you to Read Public & Private Bins. Moreover, using this API, you could also Read Versions of a specific Bin.

Root

https://api.jsonbin.io/v3

Route

Read a specific Bin
/b/<BIN_ID>
Read a specific Bin Version
/b/<BIN_ID>/<BIN_VERSION>
Read Latest Version of the Bin (without the need of specifying the exact version)
/b/<BIN_ID>/latest

Info Using /latest will always return the latest version of the bin.

Request Type

GET

Request Headers

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

Request Header Value Required
X-Master-Key <API_KEY> Yes
X-Bin-Meta <true / false> No
X-Dot-Path <JSON_ACCESSOR> No
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-Meta Optional

You may pass X-Bin-Meta header with a value of false. Doing this will omit all the metadata of the bin and will simply return the data you have stored.

X-Dot-Path Optional

Using X-Dot-Path, you could access specific data from the bin instead of the entire bin. To access a particular data, you could use JSON accessors, like, for eg, users[0].firstName.

Info You need to enable the Early Releases flag on the My Account (Summary) page, under Preferences.

Code Samples

  • cURL
  • JavaScript (ES6)
  • Python 3
  • Ruby
curl -v\
  -H "X-Master-key: <YOUR_API_KEY>" \
  --request GET \
    https://api.jsonbin.io/v3/b/<BIN_ID>/<BIN_VERSION | latest>
let req = new XMLHttpRequest();

req.onreadystatechange = () => {
  if (req.readyState == XMLHttpRequest.DONE) {
    console.log(req.responseText);
  }
};

req.open("GET", "https://api.jsonbin.io/v3/b/<BIN_ID>/<BIN_VERSION | latest>", true);
req.setRequestHeader("X-Master-Key", "<YOUR_API_KEY>");
req.send();
import requests
url = 'https://api.jsonbin.io/v3/b/<BIN_ID>/<BIN_VERSION | latest>'
headers = {
  'X-Master-Key': '<YOUR_API_KEY>'
}

req = requests.get(url, json=None, headers=headers)
print(req.text)

require 'net/http'
require 'json'

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

  http.request()
end

puts res.body

Request Response

Success Status Code: 200
With Meta Data
{
  "record": {
    "sample": "Hello World"
  },
  "metadata": {
    "id": "<BIN_ID>",
    "private": true
  }
}
Without Meta Data (using X-Bin-Meta: false header)
{
  "sample": "Hello World"
}

Info If using X-Dot-Path and the Meta is disabled, the response data type will depend upon the JSON Path you are trying to access but the Content-Type is set to JSON.

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

Bin version is invalid

Bin version you are trying to access is not valid.

You need to pass X-Master-Key in the header to read a private 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.

X-Master-Key is invalid or the bin doesn't 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.

Bin not associated to any user account

You are trying to access a bin which does not belong to any user.

Bins not associated to any user are now blocked. Contact the admin at https://jsonbin.io/contact for further info

Generally, you will never encounter this error. This error will be thrown if you are trying to access a Bin which was created without a user. These are the records which were created earlier where Authentication was not required to Create bins and hence, we have blocked these bins for countering spammy requests.

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.

Bin not found or it doesn't belong to your account

You are trying to access a bin which does not exists or it does not belong to your account. Verify the Bin Id and try again.

Bin version not found

You are trying to access a Version of a Bin which does not exist. Verify and pass a valid version else use /latest route instead.

Create a Free Account

Create an Account View Pricing