⚡ Developer & Agent Documentation

REST API & Model Context Protocol

Universal platform for programmatic micro-site generation, sequential Box Chains, client-side WebCrypto encryption, and Model Context Protocol (MCP) tool integration.

🔑 Manage API Keys & Credits 🤖 Connect MCP Server 📡 REST API Reference 🧪 Live Test Console

MCP Tool Registry

17 Tools

Links, sequential Box Chains, server lockboxes, decoding, and account quotas

Transports

HTTP & Stdio

Streamable HTTP over SSE and local Stdio executable (/usr/local/bin/bitty-mcp)

Data Storage

URL Native

Zero-database architecture; full compressed document sits in the browser URL hash

Security Model

AES-256-GCM

Client-side WebCrypto PBKDF2 encryption; zero server plaintext knowledge

🤖

Model Context Protocol (MCP) Server

Connect Claude Desktop, Cursor, Claude Code, Windsurf, or custom AI agents

Protocol 2025-06-18

Bitty Box exposes an official MCP Server that grants AI agents the native ability to generate interactive code viewers, markdown reports, sandboxed web applications, and multi-step Box Chains on demand.

Streamable HTTP Endpoint

https://bittybox.org/mcp

Alternate: /api/mcp • Accept: application/json, text/event-stream

Local Stdio Executable

/usr/local/bin/bitty-mcp

Stdio JSON-RPC transport for terminal agents

MCP Client Configurations

Add to your claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "bittybox": {
      "type": "http",
      "url": "https://bittybox.org/mcp",
      "headers": {
        "Authorization": "Bearer ",
        "Accept": "application/json, text/event-stream",
        "MCP-Protocol-Version": "2025-06-18"
      }
    }
  }
}

Add to .cursor/mcp.json or your global Cursor Settings > Features > MCP:

.cursor/mcp.json

{
  "mcpServers": {
    "bittybox": {
      "url": "https://bittybox.org/mcp",
      "headers": {
        "Authorization": "Bearer "
      }
    }
  }
}

Run in your terminal using the Claude Code CLI:

Terminal Command

claude mcp add --transport http bittybox https://bittybox.org/mcp --header "Authorization: Bearer "

Add to ~/.codeium/windsurf/mcp_config.json:

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "bittybox": {
      "serverUrl": "https://bittybox.org/mcp",
      "headers": {
        "Authorization": "Bearer "
      }
    }
  }
}

Exposed MCP Tools Reference (17)

⚡ create_bitty_link

Core Tool

Universal tool for encoding any text, code, markdown, HTML, SVG, or JSON into a permanent compressed Bitty link. The payload is compressed using GZIP Level 9 and encoded directly into the URL hash fragment. Zero server storage.

Parameter	Type	Requirement	Description
content	string	required	The document body or code to compress.
title	string	optional	Document title or filename (e.g. "report.md", "app.py").
format	enum	optional (default: auto)	"auto" \| "markdown" \| "code" \| "html" \| "json" \| "svg" \| "canvas" \| "recipe" \| "raw".
language	string	optional	Programming language for syntax highlighting (python, js, rust, go, bash, etc.).
theme	enum	optional (default: auto)	"auto" \| "dark" \| "light".
password	string	optional	AES-256-GCM encryption passcode. Payload will be encrypted client-side.
editable	boolean	optional	Open directly into the Bitty Box rich editor workspace.

Example Tool Call

{
  "content": "# Deploy Report
All 14 microservices passed canary verification.

- API: OK
- DB: OK",
  "title": "deploy-report.md",
  "format": "markdown",
  "theme": "dark"
}

⛓️ create_bitty_chain / create_box_chain

Box Chain

Create a sequential multi-page Box Chain (slide decks, progressive multi-step tutorials, guided workflows). Each box links to the next using hash routing with ordered page metadata and optional lock configurations.

Parameter	Type	Requirement	Description
title	string	required	Title of the entire box chain.
pages	array<object>	required	Array of pages (title, content, format, language, description, favicon, lockConfig).

Example Tool Call

{
  "title": "FastAPI Crash Course",
  "pages": [
    { "title": "1. Introduction", "content": "# FastAPI Quickstart
Build robust APIs fast.", "format": "markdown" },
    { "title": "2. Main App", "content": "from fastapi import FastAPI
app = FastAPI()

@app.get('/')
def root(): return {'hello': 'world'}", "format": "code", "language": "python" },
    { "title": "3. Finish", "content": "You're all set!", "format": "html" }
  ]
}

💻 create_code_bitty_link

Code Viewer

Syntax-highlighted developer code viewer with line numbers, copy button, file download, and language tags.

Parameter	Type	Requirement	Description
code	string	required	The source code snippet or file contents.
language	string	optional	Programming language (python, typescript, rust, go, bash, sql, etc.).
title	string	optional	Filename with extension (e.g. "worker.ts").

📝 create_markdown_bitty_link

Markdown

GitHub-flavored markdown reader with code highlighting, checklists, tables, blockquotes, and dark/light themes.

Parameter	Type	Requirement	Description
markdown	string	required	Markdown text document.
title	string	optional	Document title.

🌐 create_html_bitty_link

HTML App

Sandboxed, self-contained interactive mini-web apps, calculators, tools, canvas animations, and dashboards.

Parameter	Type	Requirement	Description
html	string	required	Complete HTML document string.
title	string	optional	App title.

🔍 decode_bitty_link

Decompressor

Decompresses and extracts original content, format, language, title, and metadata from any Bitty link URL.

Parameter	Type	Requirement	Description
url	string	required	The full Bitty Box URL to inspect and decompress.
password	string	optional	Passcode if the URL is AES-256-GCM encrypted.

📋 list_supported_formats

Discovery

Enumerates all supported document formats, engine features, compression schemes, and chain endpoints.

🛡️ Server-Gated Box Management (Tools 8-17)

API Key Required

Wrap URL payloads in server-enforced access policies with time windows, open limits, invite-only lists, and cryptographic passcodes.

Tool Name	Action	Key Arguments
create_box	Create server-gated box	`title`, `bittyUrl` or `payload`, `lockConfig`
set_password_lock	Attach password verification policy	`boxId`, `password`
set_time_lock	Set time release / expiration window	`boxId`, `notBefore`, `notAfter`
set_access_limit	Set maximum allowed opens	`boxId`, `maxOpens`
set_invite_only	Grant access to specific emails	`boxId`, `allowedEmails[]`
publish_box	Activate box for access	`boxId`
list_boxes	List user's active boxes	`limit`, `offset`
unlock_box	Evaluate locks and issue payload token	`boxId`, `password`, `email`
delete_box	Permanently delete and revoke box	`boxId`

📡

REST API Reference

Programmatic HTTP endpoints for link creation, chaining, decoding, and lockbox management

Base URL: https://bittybox.org

🔑 Authentication & API Keys

Public URL-native links can be created without authentication. For link attribution, credit balance tracking, and server-gated lockboxes, include your API key in either of the following headers:

Authorization: Bearer bb_live_... X-API-Key: bb_live_... X-Session-Id: <SESSION_ID>

POST /api/bitty/create Public / Bearer

Create a compressed, self-contained Bitty Link. Aliased as /api/agent/url and /api/bitty.

Request Body

{
  "content": "def add(a, b):
    return a + b",
  "title": "math.py",
  "format": "code",          // "auto" | "code" | "markdown" | "html" | "json" | "svg"
  "language": "python",      // optional language
  "theme": "dark",           // "auto" | "dark" | "light"
  "password": ""             // optional AES-256-GCM encryption passcode
}

Response (200 OK)

{
  "success": true,
  "url": "https://bittybox.org/#math.py/data:text/html;charset=utf-8;format=gz;base64,7ZVNS8NAEIZ/...",
  "title": "math.py",
  "format": "code",
  "language": "python",
  "stats": {
    "rawBytes": 38,
    "renderedBytes": 7420,
    "compressedBytes": 2390,
    "urlLength": 3280,
    "compressionRatio": "67%"
  },
  "markdownLink": "[math.py](https://bittybox.org/#math.py/...)"
}

cURL Command

curl -sS https://bittybox.org/api/bitty/create   -H "Content-Type: application/json"   -d '{"title":"demo.md","format":"markdown","content":"# Hello World
URL-native micro-sites."}'

POST /api/bitty/chain Public / Bearer

Create a sequential multi-box Box Chain. Aliased as /api/agent/box-chain and /api/bitty/box-chain.

Request Body

{
  "title": "Product Walkthrough",
  "pages": [
    { "title": "1. Overview", "content": "# Overview
Welcome!", "format": "markdown" },
    { "title": "2. Step 1", "content": "console.log('Step 1');", "format": "code", "language": "javascript" },
    { "title": "3. Summary", "content": "Complete", "format": "html" }
  ]
}

Response (200 OK)

{
  "success": true,
  "chainId": "bbc_82f10b...",
  "total": 3,
  "title": "1. Overview",
  "primaryUrl": "https://bittybox.org/#/1.-Overview/ch/bbc_82f10b...~0~3/nx/.../data:...",
  "urls": [
    "https://bittybox.org/#/1.-Overview/ch/bbc_82f10b...~0~3/nx/.../data:...",
    "https://bittybox.org/#/2.-Step-1/ch/bbc_82f10b...~1~3/nx/.../data:...",
    "https://bittybox.org/#/3.-Summary/ch/bbc_82f10b...~2~3/data:..."
  ]
}

POST /api/bitty/decode Public

Decompress any Bitty Box URL back to its original raw content. Aliased as /api/agent/inspect.

Request Body

{
  "url": "https://bittybox.org/#demo.md/data:text/html;charset=utf-8;format=gz;base64,..."
}

Response (200 OK)

{
  "success": true,
  "title": "demo.md",
  "mediatype": "text/html",
  "content": "...",
  "byteLength": 7420
}

GET /api/bitty/formats Public

Returns supported formats (markdown, code, html, json, svg, canvas, recipe, text) and platform capabilities.

GET /api/health Public

System health check, AI model status, and uptime verification.

POST /api/boxes API Key Required

Create a server-gated box with server-side policies (time window, view limits, password locks).

cURL Create Server-Gated Box

curl -sS https://bittybox.org/api/boxes   -H "Content-Type: application/json"   -H "Authorization: Bearer "   -d '{
    "title": "confidential-briefing",
    "bittyUrl": "https://bittybox.org/#brief/data:...",
    "lockConfig": {
      "timeWindow": { "enabled": true, "notAfter": "2026-12-31T23:59:59Z" },
      "openLimit": { "enabled": true, "maxOpens": 3 }
    }
  }'

🧪

Interactive API Playground

Test endpoints directly from your browser in real-time

Live Console

Preset Example:

Method & Endpoint:

Optional API Key (Bearer):

Request JSON Body:

Live Response:

// Response output will appear here after clicking "Send Request"...

⚠️

Status Codes & Errors

Standard HTTP responses and error handling

Status Code	Reason	Description
200 OK	Success	Payload compressed, decoded, or retrieved successfully.
400 Bad Request	Validation Error	Missing required `content`, malformed JSON, or payload exceeding size limits.
401 Unauthorized	Auth Failure	Missing or invalid API key on authenticated endpoints.
402 Payment Required	Insufficient Credits	Account balance has exhausted free generation quota. Top up in Accounts.
403 Forbidden	Policy Gated	Lock conditions not satisfied (e.g. invalid passcode, time expired, open limit reached).
404 Not Found	Missing Box	Server box ID does not exist or has been deleted.
429 Too Many Requests	Rate Limited	Exceeded request burst rate. Please backoff with jitter.