PrivateBinAPI 1.0.0

Basic usage

PrivateBin API is designed to be as easy to use as possible. A quick example of the most basic features is shown below:

>>> import privatebinapi
>>> send_response = privatebinapi.send("https://vim.cx", text="Hello, world!")
>>> get_response = privatebinapi.get(send_response["full_url"])
>>> get_response['text'] == "Hello, world!"
True
>>> delete_response = privatebinapi.delete(send_response["full_url"], send_response["deletetoken"])

Each function returns a modified version of the JSON received from the PrivateBin instance.

All parameters shown in the docs below are optional and may be combined in any way.

Sending a Paste

To send a paste containing nothing but text, do the following:

>>> import privatebinapi
>>> response = privatebinapi.send("https://vim.cx", text="Hello, world!")

You can expect the send function to return something similar to the following:

{
    "deletetoken": "< paste delete token >",
    "full_url": "< direct link to paste> ",
    "id": "< paste ID >",
    "passcode": "< paste passcode >",
    "status": 0,
    "url": "/?< paste ID >"
}

("5min", "10min", "1hour", "1day", "1week", "1month", "1year", "never")

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     expiration="5min"
... )

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     password="Secure123!"
... )

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     compression=None
... )

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     formatting="markdown"
... )

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     burn_after_reading=True
... )

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     discussion=True
... )

Getting a Paste

Getting a paste from a PrivateBin instance is very easy:

>>> import privatebinapi
>>> response = privatebinapi.get("https://example.com/?fakePasteLink#1234567890")

You can expect the get function to return something similar to the following:

{
    "attachment": {
        "content": b"< attachment content in bytes >",
        "filename": "< name of attachment >"
    },
    "id": '< paste ID >",
    "meta": {
        "created": < UNIX timestamp >,
        "time_to_live": < seconds until deletion >
    },
    "status": 0,
    "text": "< text content of the paste >",
    "url": "/?< paste ID >",
    "v": < encryption version 1 or 2 >}
}

>>> import privatebinapi
>>> response = privatebinapi.get(
...     "https://example.com/?fakePasteLink#1234567890",
...     password="Secure123!"
... )

Deleting a Paste

You can expect the delete function to return something similar to the following:

{
    "id": '< paste ID >",
    "status": 0,
    "url": "/?< paste ID >",
}

To delete a paste, you need its URL and delete token.

>>> import privatebinapi
>>> response = privatebinapi.delete(
...     "https://example.com/?fakePasteLink#1234567890",
...     "fake1delete2token3"
... )

Using a Proxy

All functions have an optional keyword parameter, proxies, that accepts a dictionary of proxies like you would see in the Requests package.

>>> import privatebinapi
>>> response = privatebinapi.send(
...     "https://vim.cx",
...     text="Hello, world!",
...     proxies={
...         "http": "http://example.com/proxy:80",
...         "https": "https://example.com/proxy:8080"
...     }
... )

Using Async Functions

privatebinapi.send, privatebinapi.get and privatebinapi.delete all have async analogs. They accept all the same parameters that their synchronous counterparts do.

import asyncio

import privatebinapi

async def main():
    send_response = await privatebinapi.send_async(
        "https://vim.cx",
        text="Hello, world!"
    )
    get_response = await privatebinapi.get_async(send_response["full_url"])
    delete_response = await privatebinapi.delete_async(
        send_response["full_url"],
        send_response["deletetoken"]
    )

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Both privatebinapi.send and privatebinapi.get do encryption and decryption using an executor. It will use the default executor for your event loop if executor is None.

License

PrivateBin API is offered under the MIT license.