KaguneBin Documentation

About KaguneBin

KaguneBin is a fast, minimal, anonymous pastebin built for developers who value privacy and simplicity. Inspired by the dark aesthetic of Tokyo Ghoul, the platform pairs a striking visual identity with a developer-first feature set — making it the perfect home for code snippets, logs, configuration files, and temporary data.

KaguneBin was built because most existing paste services are either bloated with ads, tied to accounts, or lack the privacy controls developers actually need. KaguneBin is the opposite: fully anonymous by default, ridiculously fast, and free of distractions.

Core Principles

• Privacy-focused — no accounts, no tracking, no nonsense.
• Developer-first — clean REST API, official Python SDK, raw access.
• Fast & lightweight — powered by FastAPI and PostgreSQL.
• Tokyo Ghoul inspired — dark, blood-red aesthetic with a sharp edge.
• Open source — fully transparent and community-driven.

Highlight Features

Website Features

Everything KaguneBin offers, in one place.

REST API Reference

The KaguneBin API is a simple REST interface. All endpoints return JSON unless otherwise noted.

Base URL

{
  "status": "ok",
  "service": "KaguneBin"
}

{
  "title": "My Snippet",
  "content": "print('Hello, Kagune')",
  "syntax": "python",
  "security": {
    "is_protected": true,
    "password": "secret123",
    "is_burn_after_read": false
  },
  "is_expiry": true,
  "expiry_date": "2026-12-31",
  "expiry_hour": 23,
  "expiry_minute": 59,
  "tz_offset_minutes": -330
}

{
  "id": "kgn_a1b2c3d4",
  "title": "My Snippet",
  "content": "print('Hello, Kagune')",
  "syntax": "python",
  "url": "/p/kgn_a1b2c3d4",
  "is_protected": true,
  "is_burn_after_read": false,
  "views": 0,
  "downloads": 0,
  "created_at": "2026-05-30T12:00:00+00:00",
  "expires_at": "2026-12-31T23:59:00+00:00",
  "security": { "is_protected": true, "is_burn_after_read": false },
  "stats": { "views": 0, "downloads": 0 },
  "timestamps": { "created_at": "2026-05-30T12:00:00+00:00", "expires_at": "2026-12-31T23:59:00+00:00" }
}

GET /api/paste/kgn_a1b2c3d4?password=secret123

{
  "id": "kgn_a1b2c3d4",
  "title": "My Snippet",
  "content": "print('Hello, Kagune')",
  "syntax": "python",
  "url": "/p/kgn_a1b2c3d4",
  "is_protected": true,
  "is_burn_after_read": false,
  "views": 42,
  "downloads": 7,
  "created_at": "2026-05-30T12:00:00+00:00",
  "expires_at": "2026-12-31T23:59:00+00:00",
  "security": { "is_protected": true, "is_burn_after_read": false },
  "stats": { "views": 42, "downloads": 7 },
  "timestamps": { "created_at": "2026-05-30T12:00:00+00:00", "expires_at": "2026-12-31T23:59:00+00:00" }
}

GET /raw/kgn_a1b2c3d4
# Response: text/plain
print('Hello, Kagune')

GET /download/kgn_a1b2c3d4
# Response: Content-Disposition: attachment; filename="kgn_a1b2c3d4.py"

Official KaguneBin Python SDK

The official Python SDK gives you a lightweight, friendly wrapper around the REST API. Perfect for automation, scripts, CLI tools, and bot integrations.

Installation

pip install kagunebin

Why use the SDK?

• Lightweight — zero bloat, single dependency.
• Simple API — readable, Pythonic method names.
• Automation friendly — ideal for CI/CD pipelines.
• Bot friendly — works seamlessly with Pyrogram, Telethon, Discord.py.

Quick Start

from kagunebin import KaguneBin

client = KaguneBin()
paste = client.create(
    title="Hello",
    content="print('Paste Fear. Share Power.')",
    syntax="python",
)
# create() returns the API JSON as a dict
print(paste["id"], paste["url"])

Constructor

client = KaguneBin(base_url="https://kagunebin.vercel.app")

create() — Create a paste

Create a new paste with optional password protection and burn-after-read.

paste = client.create(
    title="Secret Config",
    content="API_KEY=xxx",
    syntax="bash",
    password="hunter2",
    burn_after_read=True,
)
print(paste["url"])

get(paste_id, password=None) — Retrieve a paste

Returns the full paste payload as a dict.

paste = client.get("kgn_a1b2c3d4", password="hunter2")
print(paste["title"])
print(paste["content"])

raw(paste_id, password=None) — Raw text

Returns the plaintext content as a str.

text = client.raw("kgn_a1b2c3d4")
print(text)

download(paste_id, password=None) — File bytes

Returns the file content as bytes. Write it to disk yourself.

data = client.download("kgn_a1b2c3d4")
with open("snippet.py", "wb") as f:
    f.write(data)

syntaxes()

Returns a copy of every supported syntax language.

langs = client.syntaxes()
print(langs)
# ['python', 'javascript', 'typescript', 'java', 'cpp', 'c', ...]

is_valid_syntax(syntax)

Validates whether a given syntax name is supported (case-insensitive).

client.is_valid_syntax("python")   # True
client.is_valid_syntax("klingon")  # False

Telegram Bot Integration

Combine the KaguneBin SDK with Pyrogram to build a Telegram bot that turns any message into a shareable paste in seconds.

Installation

pip install pyrogram tgcrypto kagunebin

Full Bot Example

This bot listens for any text message, creates a KaguneBin paste, and replies with the URL.

from pyrogram import Client, filters
from kagunebin import KaguneBin

API_ID = 123456
API_HASH = "your_api_hash"
BOT_TOKEN = "your_bot_token"

app = Client("kagune-bot", api_id=API_ID, api_hash=API_HASH, bot_token=BOT_TOKEN)
kagune = KaguneBin()

@app.on_message(filters.text & ~filters.command(["start"]))
async def paste_handler(client, message):
    paste = kagune.create(
        title=f"From @{message.from_user.username}",
        content=message.text,
        syntax="python",
    )
    await message.reply_text(f"🩸 Paste created:\n{paste["url"]}")

@app.on_message(filters.command("start"))
async def start(client, message):
    await message.reply_text("Send me any text and I'll paste it on KaguneBin.")

app.run()

cURL Examples

Quick reference for hitting the API directly from your shell.

Create a paste

curl -X POST https://kagunebin.vercel.app/paste \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Snippet",
    "content": "print(\"Hello\")",
    "syntax": "python"
  }'

Retrieve paste details

curl https://kagunebin.vercel.app/api/paste/kgn_a1b2c3d4

Raw content

curl https://kagunebin.vercel.app/raw/kgn_a1b2c3d4

Download content

curl -O -J https://kagunebin.vercel.app/download/kgn_a1b2c3d4

Error Handling

KaguneBin uses standard HTTP status codes. All errors return JSON with a consistent shape.

Error Response Example

{
  "success": false,
  "error": "unauthorized",
  "message": "Invalid password for this paste.",
  "status": 401
}

Frequently Asked Questions

Open Source

KaguneBin is fully open source. Contributions, issues, and stars are always welcome.