15 API

El RIDO edited this page 2019-05-27 19:12:32 +02:00

Table of Contents

• As of Version 1.3
• As of Version 0.22
• Until Version 0.21.1
• Legend

PrivateBin uses AJAX requests for certain operations.

As of Version 1.3

All JSON-API requests need to be sent with the HTTP header X-Requested-With: JSONHttpRequest. The query strings below would be appended after the ? in the URL, i.e. query string foo on the site URL of https://example.com/privatebin/ would become https://example.com/privatebin/?foo. The full PUT and POST data now is expected to be sent as a JSON string instead of URL-encoded form data. Please see the encryption format page for details on the JSON string format.

Action	Type	Query String	Data to send	Result (JSON-LD)
retrieve paste (and its comments)	GET	[pasteID]	(no data)	paste.jsonld
create paste	PUT	[pasteID]	{"v":2,"adata":[["base64 encoded iv","base64 encoded salt",100000,256,128,"aes","gcm","zlib"],"plaintext",0,0],"ct":"base64 of cipher text","meta":{"expire":"5min"}}	{"status":0, "id":"[pasteID]", "url":"[serverAddress?pasteID]", "deletetoken":"[deleteToken]"}
create paste	POST	(empty query string)	{"v":2,"adata":[["base64 encoded iv","base64 encoded salt",100000,256,128,"aes","gcm","zlib"],"plaintext",0,0],"ct":"base64 of cipher text","meta":{"expire":"5min"}}	{"status":0, "id":"[pasteID]", "url":"[serverAddress?pasteID]", "deletetoken":"[deleteToken]"}
create comment	PUT	[commentID]	{"v":2,"adata":["base64 encoded iv","base64 encoded salt",100000,256,128,"aes","gcm","zlib"],"ct":"base64 of cipher text"}	{"status":0, "id":"[commentID]", "url":"[serverAddress?commentID]"}
create comment	POST	(empty query string)	{"v":2,"adata":["base64 encoded iv","base64 encoded salt",100000,256,128,"aes","gcm","zlib"],"ct":"base64 of cipher text"}	{"status":0, "id":"[commentID]", "url":"[serverAddress?commentID]"}
delete paste	DELETE	(empty query string)	{"pasteid":"[pasteID]", "deletetoken":"[deletetoken]"}	{"status":0, "id":"[pasteID]"}
delete paste	POST	(empty query string)	{"pasteid":"[pasteID]", "deletetoken":"[deletetoken]"}	{"status":0, "id":"[pasteID]"}
Error during any of the above	N/A	N/A	N/A	{"status":1, "message":"[errormessage]"}

As of Version 0.22

All JSON-API requests need to be sent with the HTTP header X-Requested-With: JSONHttpRequest. The query strings below would be appended after the ? in the URL, i.e. query string foo on the site URL of https://example.com/privatebin/ would become https://example.com/privatebin/?foo.

Action	Type	Query String	Data to send	Result (JSON-LD)
retrieve paste (and its comments)	GET	[pasteID]	(no data)	paste.jsonld
create paste	PUT	[pasteID]	data=[cipherdata]& expire=[expireID]& formatter=[formatID]& burnafterreading=[1/0]& opendiscussion=[1/0]	paste.jsonld (including deletetoken)
create paste	POST	(empty query string)	data=[cipherdata]& expire=[expireID]& formatter=[formatID]& burnafterreading=[1/0]& opendiscussion=[1/0]	paste.jsonld (including deletetoken)
create comment	PUT	[commentID]	data=[cipherdata]& parentid=[parentID]& pasteid=[pasteID]& nickname=[cipherdata]	{"status":0, "id":"[commentID]"}
create comment	POST	(empty query string)	data=[cipherdata]& parentid=[parentID]& pasteid=[pasteID]& nickname=[cipherdata]	{"status":0, "id":"[commentID]"}
delete paste (burn after reading)	DELETE	(empty query string)	pasteid=[pasteID]& deletetoken=burnafterreading	{"status":0, "id":"[pasteID]"}
delete paste (burn after reading)	POST	(empty query string)	pasteid=[pasteID]& deletetoken=burnafterreading	{"status":0, "id":"[pasteID]"}
delete paste	DELETE	(empty query string)	pasteid=[pasteID]& deletetoken=[deletetoken]	{"status":0, "id":"[pasteID]"}
delete paste	POST	(empty query string)	pasteid=[pasteID]& deletetoken=[deletetoken]	{"status":0, "id":"[pasteID]"}
Error on any of the above	N/A	N/A	N/A	{"status":1, "message":"[errormessage]"}

Until Version 0.21.1

The query strings below would be appended after the ? in the URL, i.e. query string foo on the site URL of https://example.com/privatebin/ would become https://example.com/privatebin/?foo.

Action	Type	Query String	Data to send (JSON)	Result (JSON)
retrieve paste (and its comments)	GET	[pasteID]&json	(no data)	{"status":0, "id":"[pasteID]", "messages": [array of one paste and its comments if any]}
create paste	POST	(empty query string)	{"data":"[cipherdata]", "expire":"[expireID]", "burnafterreading":[1/0], "opendiscussion":[1/0]}	{"status":0, "id":"[pasteID]", "deletetoken":[token]}
create comment	POST	(empty query string)	{"data":"[cipherdata]", "parentid":"[parentID]", "pasteid":[pasteID], "nickname":[cipherdata]}	{"status":0, "id":"[pasteID]"}
delete paste (only for burn after reading pastes)	GET	pasteid=[pasteID]&deletetoken=burnafterreading	(no data)	{"status":0, "id":"[pasteID]"}
Error on any of the above	N/A	N/A	N/A	{"status":1, "message":"[errormessage]"}

Legend

• pasteID: ID of the paste, 16 characters long, hexadecimal
• parentID: ID of the comments parent (paste ID or comment ID), 16 characters long, hexadecimal
• commentID: ID of the comment, 16 characters long, hexadecimal
• cipherdata: JSON string containing base64 encoded data, see encryption format
• expireID: expiration key as defined in the configuration file of the service
• formatID: format key as defined in the configuration file of the service
• metadata: various properties of the paste or the comment.
• deletetoken: the delete token is returned only on creation of a paste and can be used to delete it and its comments