Create Collections API

Group JSON bins using the Collections API. You could later fetch these bins using the Collections Fetch Bins API.

Moreover, you could also use Collections to validate your JSON records using Schema Doc Validation.

You could attach a Schema doc to validate the JSON records before you add them to your Collection.




Request Type


Request Headers

Below are the list of Accepted Request Headers if you are trying to Create a Collection.

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

X-Collection-Name is a required header which sets the Collection Name. You cannot set a name more than 32 characters.

Code Samples

  • cURL
  • JavaScript (ES6)
  • Python 3
  • Ruby
curl -v\
  -H "X-Collection-Name: My Collection" \
  -H "X-Master-key: <YOUR_API_KEY>" \
  --request POST \
let req = new XMLHttpRequest();

req.onreadystatechange = () => {
  if (req.readyState == XMLHttpRequest.DONE) {
};"POST", "", true);
req.setRequestHeader("X-Collection-Name", "My Collection");
req.setRequestHeader("X-Master-Key", "<YOUR_API_KEY>");
import requests
url = ''
headers = {
  'X-Collection-Name': 'My Collection',
  'X-Master-Key': '<YOUR_API_KEY>'
data = {}

req =, json=data, headers=headers)
require 'net/http'
require 'json'

uri = URI("")
res = Net::HTTP.start(, uri.port, use_ssl: true) do |http|
  req =
  req['X-Collection-Name'] = 'My Collection'
  req['X-Master-Key'] = '<YOUR_API_KEY>'

puts res.body

Request Response

Success Status Code: 200
  "record": "<RECORD_ID>",
  "metadata": {
    "createdAt": "<DATE/TIME>",
    "name": "<true/false>"
Error Status Code: 400, 401, 403
  "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 X-Collection-Name header to set a name for the Schema Doc

X-Collection-Name header is compulsory to Create a Collection. Hence, pass the header to fix this issue.

Name of the Collection cannot be above 32 characters

When you set the name of the collection using X-Collection-Name, it should not be longer than 32 characters.

Invalid X-Collection-Id provided

Check if the X-Collection-Id is valid and belongs to your account.

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.

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.

You cannot create more than 10 collections. Please delete a Collection and try again.

As the message says, you cannot create more than 10 collections in your account. If you wish to create more then please Contact Us.

You cannot create more than 1 collection in Free Trial. Consider upgrading to the Pro plan to create upto 10 collections.

Free Trial users can only create 1 collection. For creating more, consider upgrading your account to Pro.

Requests exhausted. Buy additional requests at

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