🤖 Agent-native creation protocol

Bitty Box Agent Handshake

Everything an AI agent needs to create, inspect, lock, and hand off portable micro-web apps through Bitty Box. Use MCP when your agent runtime supports tools; use REST when you need raw HTTP. The human surface stays /edit. The agent layer runs underneath it like a mischievous compression engine.

Read machine discovery Open full API docs Manage API keys

Agent decision tree

01 / Tools

Your runtime speaks MCP?

Connect to /mcp and call create_html_bitty_link, create_markdown_bitty_link, create_bitty_chain, or create_box_chain.

02 / HTTP

Only have fetch/curl?

POST content to /api/agent/url. It is a clean agent alias for /api/bitty/create.

03 / Gates

Need locks or limits?

Create the URL first, then wrap it with /api/boxes and lock endpoints for password, time, opens, or invite-only control.

MCP client configuration

Use Streamable HTTP. API keys are optional for public link creation but recommended for attribution, credits, and box management.

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

REST create URL

For agents without MCP, POST a payload and receive a portable Bitty Box URL plus stats, QR data, warnings, and embed snippets.

curl -sS https://bittybox.org/api/agent/url \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "title": "agent-built-demo",
    "format": "html",
    "content": "<!doctype html><html><body><h1>Hello from an agent</h1></body></html>",
    "theme": "dark"
  }'

REST create Box Chain

POST ordered pages and receive an entry URL plus every chained box URL. The first URL links to the second, and so on.

curl -sS https://bittybox.org/api/agent/box-chain \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "title": "agent-chain-demo",
    "pages": [
      { "title": "Intro", "format": "markdown", "content": "# Intro\nStart here.", "favicon": "📦" },
      { "title": "Code", "format": "code", "language": "javascript", "content": "console.log(\"next box\");" },
      { "title": "Finish", "format": "html", "content": "<h1>Done</h1><p>Last box.</p>" }
    ]
  }'

Inspect / decode a Bitty link

Use this before modifying an existing Bitty Box link or when a user drops you a URL and asks for a change.

curl -sS https://bittybox.org/api/agent/inspect \
  -H 'Content-Type: application/json' \
  -d '{ "url": "https://bittybox.org/#agent-built-demo/data:text/html;charset=utf-8;format=gz;base64,<payload>" }'

Validate before generating

Cheap preflight for content size, detected format, and URL-risk hints. Use it when your agent is about to shove a whale through a straw.

curl -sS https://bittybox.org/api/agent/validate \
  -H 'Content-Type: application/json' \
  -d '{ "format": "markdown", "content": "# Launch brief\nShip the weird thing." }'

Core endpoints

Use	Endpoint	Notes
Create URL-native artifact	`POST /api/agent/url` `POST /api/bitty/create`	Fields: `content`, `title`, `format`, `language`, `theme`, `password`, `editable`.
Create Box Chain	`POST /api/agent/box-chain` `POST /api/agent/chain` `POST /api/bitty/box-chain` `POST /api/bitty/chain`	Fields: `pages[]`, optional `title`, `chainId`, `domain`. Page fields match the human Studio model.
Inspect/decode	`POST /api/agent/inspect` `POST /api/bitty/decode`	Fields: `url`, optional `password`. Chain metadata is returned when present.
Capabilities	`GET /api/agent/capabilities` `GET /agents.json`	Machine-readable discovery contract for crawlers and agents.
Formats	`GET /api/bitty/formats`	Supported renderers and feature flags.
MCP tools	`POST /mcp`	Streamable HTTP MCP server. Use `Accept: application/json, text/event-stream`.
Lockable boxes	`POST /api/boxes` `POST /api/boxes/:id/lock/password` `POST /api/boxes/:id/lock/time` `POST /api/boxes/:id/lock/access-limit`	Wrap a Bitty URL with server-gated policy when a raw public URL is too exposed.

MCP tool surface

tool

`create_bitty_link`

tool

`create_bitty_chain`

tool

`create_box_chain`

tool

`create_code_bitty_link`

tool

`create_markdown_bitty_link`

tool

`create_html_bitty_link`

tool

`decode_bitty_link`

tool

`list_supported_formats`

tool

`create_box`

tool

`set_password_lock`

tool

`set_time_lock`

tool

`set_access_limit`

tool

`set_invite_only`

tool

`publish_box`

tool

`list_boxes`

tool

`unlock_box`

tool

`delete_box`

Rules agents must not break

Use /mcp when your runtime supports MCP Streamable HTTP; otherwise use POST /api/agent/url.
Use create_bitty_chain, create_box_chain, POST /api/agent/chain, or POST /api/agent/box-chain for multi-box chains.
Prefer POST for non-trivial payloads; use GET only for tiny smoke tests.
Set format explicitly when you already know the artifact type; use auto only when handing Bitty Box raw mixed content.
For executable HTML, include a complete document with its own CSS and JS. The resulting URL renders in a sandboxed browser surface.
For private or time/limit-gated delivery, create a URL first, then wrap it with /api/boxes and lock endpoints.

Lockable box handoff

Use boxes when you need server-side expiry, limited opens, password locks, invite-only access, or a future policy wrapper.

# 1) Create a URL-native Bitty link with /api/agent/url.
# 2) Wrap it as a server-gated box.
curl -sS https://bittybox.org/api/boxes \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "title": "client-deliverable",
    "bittyUrl": "<BITTY_URL>",
    "lockConfig": {
      "timeWindow": { "enabled": true, "notAfter": "2026-12-31T23:59:00Z" },
      "openLimit": { "enabled": true, "maxOpens": 5 }
    }
  }'

Security & portability warnings

URL-native links are portable but not secret. Treat unencrypted URLs as public bearer artifacts.
Very long URLs may fail in some chat apps, QR scanners, mobile browsers, or redirectors.
Server-gated boxes enforce locks at unlock time; URL-only links are enforced only by their encoded encryption state.
Generated HTML runs inside the Bitty Box viewer context; never assume it has access to third-party cookies or hidden server credentials.