{"name":"bittybox-agent-handshake","title":"Bitty Box Agent Handshake","protocol":"bittybox-url-native-micro-web","version":"2.0.0","baseUrl":"https://bittybox.org","primaryHumanSurface":"/edit","discovery":{"html":"/agents","json":"/agents.json","wellKnown":"/.well-known/bittybox-agent.json","capabilities":"/api/agent/capabilities","apiDocs":"/api/docs"},"authentication":{"optionalForPublicCreate":true,"headerOptions":["Authorization: Bearer <YOUR_API_KEY>","X-API-Key: <YOUR_API_KEY>"],"apiKeyPrefix":"bb_live_","manageKeys":"/accounts","note":"Unauthenticated creation works for public URL-native links. Account/API-key calls can attribute links, use credits, and manage server-gated boxes."},"mcp":{"endpoint":"/mcp","alternateEndpoint":"/api/mcp","absoluteEndpoint":"https://bittybox.org/mcp","transport":"streamable-http","protocolVersionHeader":"MCP-Protocol-Version","acceptHeader":"application/json, text/event-stream","tools":["create_bitty_link","create_bitty_chain","create_box_chain","create_code_bitty_link","create_markdown_bitty_link","create_html_bitty_link","decode_bitty_link","list_supported_formats","create_box","set_password_lock","set_time_lock","set_access_limit","set_invite_only","publish_box","list_boxes","unlock_box","delete_box"]},"rest":{"createUrl":{"methods":["POST","GET"],"path":"/api/agent/url","canonical":"/api/bitty/create"},"createChain":{"methods":["POST","GET"],"path":"/api/agent/chain","canonical":"/api/bitty/chain"},"createBoxChain":{"methods":["POST","GET"],"path":"/api/agent/box-chain","canonical":"/api/bitty/box-chain"},"inspectUrl":{"methods":["POST","GET"],"path":"/api/agent/inspect","canonical":"/api/bitty/decode"},"validatePayload":{"methods":["POST"],"path":"/api/agent/validate"},"formats":{"methods":["GET"],"path":"/api/bitty/formats"},"boxes":{"create":{"methods":["POST"],"path":"/api/boxes"},"status":{"methods":["GET"],"path":"/api/boxes/:id/status"},"unlock":{"methods":["POST"],"path":"/api/boxes/:id/unlock"},"payload":{"methods":["GET"],"path":"/api/boxes/:id/payload?grant=<TOKEN>"}}},"payload":{"acceptedInputs":["content","code","markdown","html","json","svg","pages"],"formats":["auto","text","markdown","code","html","json","svg","canvas","recipe"],"linkModel":"The payload is compressed into the URL hash. Browser hash fragments are shareable and visible to anyone holding the link.","chainModel":"Pass pages[] to create a Box Chain. Each page accepts content, title, format, language, theme, description, favicon, image, password, and Studio-compatible lockConfig metadata.","recommendedUrlLengthBudget":12000,"hardRequestBodyLimit":"15mb","encryption":"Pass password to create AES-256-GCM encrypted URL payloads. Do not place live secrets in unencrypted boxes."},"agentInstructions":["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.","Do not encode API keys, OAuth tokens, private customer data, or credentials unless the payload is encrypted and the recipient has the password through a separate channel.","If urlLength is high, shorten assets, externalize heavy media, or wrap the payload in a server-gated box instead of forcing a monster URL."],"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."]}