API Reference

CORS Enabled

Important:

API v1 is DEPRECATED as of June 26th 2018. Please refer to API v2 for latest security updates, features and enhancements. Documentation page for API v1 will be removed before August 1st 2018.

Request A JSON

GET /b/:id
Private Bins

In-order to request a private bin, you need to pass a secret-key key in the request headers. You can find your security key here once you sign-in. This key is required every time when you request for a bin or an updated version of the bin if the record which is stored is private.

Request Specific Version (if you update)
GET /b/:id/:version   #if you update the JSON using the Update API
Request Latest Version (if you update)
GET /b/:id/latest   #if you update the JSON using the Update API
Add /pretty (Optional parameter) for pretty JSON response
GET /b/:id/pretty
GET /b/:id/(:version|latest)/pretty #if you update the JSON
On Success (Server Response)
STATUS
200 OK
On Error (Server Response)
STATUS
422 Unprocessable Entity
DATA
success: false, (Invalid snippet ID | Snippet not found)
Example (jQuery) - Request Original Version
  $.get('//jsonbin.io/b/591a01528c8d6246313db019', function(data) {
  //use the data here
  console.log(data); //returns json object
  });
Demo Fiddle


Example (jQuery) - Request Specific Version
  $.get('//jsonbin.io/b/591a01528c8d6246313db019/1', function(data) {
  //use the data here
  console.log(data); //returns json object
  });
Demo Fiddle

Create A JSON

POST (RAW) /b/new
ON SUCCESS (SERVER RESPONSE)
STATUS
200 OK
DATA
success: true,
data: {STRINGIFIED_JSON},
id: SNIPPET_ID
On Error (Server Response)
STATUS
422 Unprocessable Entity
DATA
success: false,
(Snippet (parameter is missing | cannot be blank, invalid json, please try again))
Example (Raw - Type JSON)
  {
  "snippet": "{\"name\": \"John Doe\"}" //Stringified JSON
  }
Private Bins

In-order to create a private bin, you need to pass a secret-key key in the request headers. You can find your security key here once you sign-in. If secret-key is missing, the record won't be stored as a private record.

List Public Bins in your account (Follow this only if you want to list the public bins in yor account.)

In-order to list a public bin in your account, you need to pass a private key with a value of false along with the secret-key key in the request headers. You can find your security key here once you sign-in. If secret-key is missing, the record will be public but it won't list in your account.


Note: You need not pass the secret-key in the headers to fetch public bins. Also, public bins can be updated by any user having the bin ID.


Update A JSON

POST (RAW) /b/update/:id
On Success (Server Response)
STATUS
200 OK
DATA
success:true,
data:{STRINGIFIED_JSON},
version: {SNIPPET_VERSION_ID},
parentId: {PARENT_SNIPPET_ID}
On Error (Server Response)
STATUS
422 Unprocessable Entity
DATA
success: false,
(Snippet not found | Snippet parameter is missing | Invalid JSON, Please try again | Something went wrong)
Example (Raw - Type JSON)
  {
  "snippet": "{\"name\": \"John Doe\", \"newdata\": \"new version will be created\"}" //Stringified JSON
  }
Private Bins

In-order to update a private bin, you need to pass a secret-key key in the request headers. You can find your security key here once you sign-in. You cannot update a private record without providing security-code key in the request header.

ROOT

https://api.jsonbin.io/

CREATE API

Create a public bin or a private bin. Creating a public bin will be accessible by anyone having the bin ID, whereas accessing a private bin will require a secret-key. You can find a secret-key on the API Keys page after signing in.

Create a new bin
Request Type Request Headers
POST
  • content-type : application/json
  • secret-key : <SECRET_KEY>
  • private : false (default: true if creating a private bin)
  • collection-id: <COLLECTION_ID>
/b
let bin = {
  name: 'John Doe',
  age: 21,
  hobbies: ['Football', 'Stamp Collection']
}

$.ajax({
  url: 'https://api.jsonbin.io/b',
  type: 'POST',
  contentType: 'application/json',

  /* headers required ONLY if you are creating a private bin or you want to create a public bin
  and also list the same in your account by passing private: false */
  headers: {
    'secret-key': <SECRET_KEY>,
    'private': false,
    'collection-id': <COLLECTION_ID>
  },
  data: JSON.stringify(bin),
  success: (data) => {
    console.log(data);
  },
  error: (err) => {
    console.log(err.responseJSON);
  }
});
Success Response
Status Code Response Type Response Data
200 JSON
Key Value Type
success true Boolean
data <bin_data> Object
id <bin_id> String
private true / false Boolean
Error Response
Error Message / How to fix? Response

Error: Expected content type - application/json

Fix: Pass content-type: application/json in header

Code Type
422 Object

Error: JSON cannot be empty

Fix: JSON object shouldn't be empty

Code Type
422 Object

Error: Invalid secret key provided.

Fix: Trying to create a private bin with incorrect secret-key. In-order to get a secret key, refer to API Keys page.

Code Type
401 Object

Error: Invalid Collection ID

Fix: Pass a valid Collection ID

Code Type
422 Object

READ API

Request a bin you created or a specific version if you updated a bin or request for a latest data of the updated bin.

Request Type Request Headers
GET
  • secret-key : <SECRET_KEY>
Read a Bin
/b/:id
$.ajax({
  url: 'https://api.jsonbin.io/b/591a01528c8d6246313db019',
  type: 'GET',
  headers: { //Required only if you are trying to access a private bin
    'secret-key': <SECRET_KEY>
  },
  success: (data) => {
    console.log(data);
  },
  error: (err) => {
    console.log(err.responseJSON);
  }
});
Read a Bin Version
/b/:id/(:version|latest)
$.ajax({
  /* We explicitly mention to fetch version 1 of this bin */
  url: 'https://api.jsonbin.io/b/591a01528c8d6246313db019/1',
  type: 'GET',
  headers: { //Required only if you are trying to access a private bin
    'secret-key': <SECRET_KEY>
  },
  success: (data) => {
    console.log(data);
  },
  error: (err) => {
    console.log(err.responseJSON);
  }
});
Success Response
Status Code Response Type Response Data
200 JSON
Key Value Type
data <bin_data> Object
Error Reesponse
Error Message / How to fix? Response

Error: Invalid bin ID

Fix: Pass a valid bin ID. IDs are case-insensitive.

Code Type
422 Object

Error: Need to provide a secret-key to READ private bins

Fix: You need to pass a valid secret-key in headers if you are trying to READ a secret bin. In-order to get a secret key, refer to API Keys page.

Code Type
401 Object

Error: Invalid secret-key provided

Fix: Make sure you provide a correct secret key to access private bins. In-order to get a secret key, refer to API Keys page.

Code Type
401 Object

Error: Bin not found

Fix: Provide a valid bin ID.

Code Type
404 Object

Error: Bin version not found

Fix: Provide a valid bin version

Code Type
404 Object

UPDATE API

Every time a bin has been updated, it will create a new version for that bin, thus, preserving all the previous data. Refer to READ API for accessing updated bins.

Request Type Request Headers
PUT
  • content-type : application/json
  • secret-key : <SECRET_KEY>
Important:

Bin privacy cannot be updated once the bin is created. A public bin cannot be made private or vice-versa.

Update A Bin
/b/:id
let bin = {
  name: 'Sam Smith',
  age: 29,
  hobbies: ['Hot Wheels Collector', 'Cooking', 'Surfing']
}

$.ajax({
  url: 'https://api.jsonbin.io/b/591a01528c8d6246313db019',
  type: 'PUT',
  contentType: 'application/json',
  data: JSON.stringify(bin),
  success: (data) => {
    console.log(data);
  },
  error: (err) => {
    console.log(err.responseJSON);
  }
});
    
Success Response
Status Code Response Type Response Data
200 JSON
Key Value Type
data <bin_data> Object
success true Boolean
version <version_id> Integer
parentId <parent_bin_id> String
Error Response
Error Message / How to fix? Response

Error: Expected content type - application/json

Fix: Pass content-type: application/json in header

Code Type
422 Object

Error: Invalid Bin ID

Fix: Pass a valid bin ID. IDs are case-insensitive.

Code Type
422 Object

Error: JSON cannot be empty

Fix: JSON object shouldn't be empty

Code Type
422 Object

Error: Bin not found

Fix: Provide a valid bin ID.

Code Type
404 Object

Error: Need to provide a secret-key to UPDATE private bins

Fix: You need to pass a valid secret-key in headers if you are trying to UPDATE a secret bin. In-order to get a secret key, refer to API Keys page.

Code Type
401 Object

Error: Invalid secret key provided

Fix: Trying to update a private bin with incorrect secret-key. In-order to get a secret key, refer to API Keys page.

Code Type
401 Object

Delete API

Delete a public bin or a private bin which belongs to you. Deleting a public bin which was created without a secret-key is not allowed. You can delete the bins only if it was a private or public if created by passing your secret-key.

Important:

Deleting a bin will delete the bin data and all the versions of that bin permanently.

Request Type Request Headers
DELETE
  • secret-key : <SECRET_KEY>
/b/:id
$.ajax({
  url: 'https://api.jsonbin.io/b/<BIN_ID>', //replace <BIN_ID> with your Bin ID
  type: 'DELETE',
  headers: {
    'secret-key': <SECRET_KEY>,
  },
  success: (data) => {
    console.log(data);
  },
  error: (err) => {
    console.log(err.responseJSON);
  }
});

COLLECTION APIs

CREATE a collection

Before you add a record to a Collection, you need to create a Collection.

/c
Important:

You need to pass name key in the objct to CREATE a Collection. Check the sample code below for more information. Also note that any other key passed with the name key will not be stored.

Request Type Request Headers
POST
  • content-type : application/json
  • secret-key : <SECRET_KEY>
let bin = {
  name: 'My New Collection' //COMPULSORY
}

$.ajax({
  url: 'https://api.jsonbin.io/c/',
  type: 'POST',
  contentType: 'application/json',
  headers: {
    'secret-key': <SECRET_KEY>,
  },
  data: JSON.stringify(bin),
  success: (data) => {
    console.log(data);
  },
  error: (err) => {
    console.log(err.responseJSON);
  }
});
Success Response
Status Code Response Type Response Data
200 JSON
Key Value Type
success true Boolean
data { name: <collection_name> } Object
collectionID <collection_id> String
Error Response
Error Message / How to fix? Response

Error: Expected content type - application/json

Fix: Pass content-type: application/json in header

Code Type
422 Object

Error: Name key cannot be blank

Fix: Pass name in JSON body

Code Type
422 Object

Error: Collection Name length should be more than 2 characters and less than 33 characters

Fix: Error message says it all.

Code Type
422 Object

Error: Invalid secret key provided.

Fix: Provide a valid secret-key in the header.

Code Type
401 Object

Error: Need to provide a secret-key to CREATE a Collection.

Fix: Provide a secret-key in the header.

Code Type
401 Object
UPDATE a Collection

For now, only name of the Collection can be updated. Inorder to UPDATE the Collection name, use the below API end-point.

/c/:id
Request Type Request Headers
PUT
  • content-type : application/json
  • secret-key : <SECRET_KEY>
let bin = {
  name: 'My Updated New Collection'
}

$.ajax({
  url: 'https://api.jsonbin.io/c/<COLLECTION_ID>',
  type: 'POST',
  contentType: 'application/json',
  headers: {
    'secret-key': <SECRET_KEY>,
  },
  data: JSON.stringify(bin),
  success: (data) => {
    console.log(data);
  },
  error: (err) => {
    console.log(err.responseJSON);
  }
});
Success Response
Status Code Response Type Response Data
200 JSON
Key Value Type
success true Boolean
data { name: <collection_name> } Object
collectionID <collection_id> String
Error Response
Error Message / How to fix? Response

Error: Expected content type - application/json

Fix: Pass content-type: application/json in header

Code Type
422 Object

Error: You need to provide a name key.

Fix: Pass name in JSON body

Code Type
422 Object

Error: Name key cannot be blank.

Fix: Pass a name for the Collection.

Code Type
422 Object

Error: Collection not found

Fix: Pass a valid collection-id

Code Type
422 Object

Error: Collection Name length should be more than 2 characters and less than 33 characters

Fix: Error message says it all.

Code Type
422 Object

Error: Invalid secret key provided.

Fix: Provide a valid secret-key in the header.

Code Type
401 Object

Error: Invalid Collection ID

Fix: Provide a valid collection-id in the header.

Code Type
401 Object

Error: Need to provide a secret-key to UPDATE Collections.

Fix: Provide a secret-key in the header.

Code Type
401 Object

EXPERIMENTAL APIs

Important:

Experimental APIs will be quirky in nature due to rapid development. We would recommend to use our Stable API end-points unless you need to use Experimental APIs. For more information, refer to our FAQ section for more info on Experimental APIs.

REQUEST VERSIONS API

Use this API to fetch versions of a particular bin.

Request Type Request Headers
GET
  • secret-key : <SECRET_KEY>
/e/:id/versions
$.ajax({
  url: 'https://api.jsonbin.io/e/591a01528c8d6246313db019/versions',
  type: 'GET',
  headers: { //Required only if you are trying to access a private bin
    'secret-key': <SECRET_KEY>
  },
  success: (data) => {
    console.log(data);
  },
  error: (err) => {
    console.log(err.responseJSON);
  }
});
Success Response
Status Code Response Type Response Data
200 JSON
Key Value Type
binVersions <bin_version_data> Array with Nested Objects
Error Reesponse
Error Message / How to fix? Response

Error: Invalid bin ID

Fix: Pass a valid bin ID. IDs are case-insensitive.

Code Type
422 Object

Error: Need to provide a secret-key to READ private bins

Fix: You need to pass a valid secret-key in headers if you are trying to READ a secret bin. In-order to get a secret key, refer to API Keys page.

Code Type
401 Object

Error: Invalid secret-key provided

Fix: Make sure you provide a correct secret key to access private bins. In-order to get a secret key, refer to API Keys page.

Code Type
401 Object

Error: Bin not found

Fix: Provide a valid bin ID.

Code Type
404 Object

Error: No versions found

Note: This error is thrown if the bin is not having any versions.

Code Type
404 Object