{"ok": true, "data": {"schema": "zzd_developer_rest_capabilities_v1", "api_version": "2026-07-31", "base_path": "/api/v1", "transport": {"kind": "https_rest", "response_format": "application/json"}, "origin_policy": {"canonical_host_only": "https://zzd.show", "code_host_available": false}, "authentication": {"scheme": "Bearer", "header_example": "Authorization: Bearer <developer credential>", "session_cookie_fallback": false, "legacy_cli_token_fallback": false, "credential_control_plane": {"authentication": "signed-in browser session plus CSRF for mutations", "list": "/api/v1/developer-credentials/", "create": "/api/v1/developer-credentials/create/", "create_example": {"label": "Codex workstation", "scopes": ["identity:read", "shows:read", "shows:write", "assets:write"], "expires_in_days": 30}, "revoke": "/api/v1/developer-credentials/{credential_id}/revoke/", "token_visibility": "returned once at creation; store in a local secret manager and never commit it"}}, "response_envelope": {"success": {"ok": true, "data": "<resource>"}, "error": {"ok": false, "error": {"code": "<stable_code>", "message": "<message>", "details": "<optional>"}}}, "lifecycle": {"mutation_default": "draft", "draft_flags": {"private": true, "hidden": true}, "publish_route_id": "publication", "publish_requires": ["shows:publish", "confirm=true", "preflight_pass"], "publication_preflight": {"metadata": ["nonblank title", "nonblank description", "prompt at least 80 characters", "category", "at least one tag"], "presentation": ["verified thumbnail", "at least one HTML Piece"], "source": ["compiled is empty", "unplug is false", "source-size limits pass", "forbidden runtime scan passes"]}}, "schemas": {"show_write": {"required_on_create": ["title"], "allowed_fields": ["title", "desc", "prompt", "context", "category", "tags", "cdns", "esm"], "fields": {"title": "nonblank string, max 50 characters", "desc": "string, max 255 characters", "prompt": "UTF-8 string, max 131072 bytes; publication requires at least 80 characters", "context": "owner-unique optional string, max 255 characters", "category": "lowercase slug", "tags": "array of up to 24 strings", "cdns": "array of bounded HTTPS dependency URLs", "esm": "array that is an exact subset of cdns"}, "server_controlled": ["id", "author", "private", "hidden", "temp", "compiled", "unplug", "sale", "balance"]}, "piece_replace": {"body": {"pieces": "non-empty ordered array"}, "piece_fields_exactly": ["generic", "name", "raw"], "generic": ["html", "css", "js"], "name": "unique safe basename, max 30 characters", "compiled": "always empty and not accepted as input", "unplug": "always false and not accepted as input"}, "publication": {"body": {"action": "publish or unpublish", "confirm": true}}, "collection": {"create_fields": {"title": "required, max 20 characters", "desc": "max 255 characters"}}, "runtime_identity_baas": {"namespaces": "1 to 8 bounded lowercase slugs", "guest_write": "must be false; anonymous writes are temporarily disabled in REST v1", "guest_ttl_days": "1 to 30", "state_max_bytes": 65536}}, "safety": {"ownership": "Every non-public resource operation is restricted to the credential owner.", "moderation": "Existing active Show creation restrictions also block REST creation and publication.", "field_policy": "Unknown fields are rejected; server-controlled fields cannot be supplied.", "source_policy": "Pieces are source-only html/css/js; compiled blobs, unplugged runtimes, hidden runtimes, and unsafe dynamic execution are rejected.", "dependencies": "Frameworks are supported through bounded HTTPS cdns; esm must be an exact subset of cdns. Local/private hosts and credential-bearing URLs are rejected.", "assets": "Allowlisted byte uploads only; drafts stay outside public media and are served through ownership-checked routes. Publication promotes a public copy; returning to draft removes it.", "baas": "Only a bounded private runtime-identity profile is provisioned by this API."}, "limits": {"json_body_bytes": 3145728, "pieces_per_show": 32, "piece_source_bytes": 524288, "piece_source_total_bytes": 2097152, "asset_bytes": 52428800, "account_asset_bytes": 1073741824, "thumbnail_bytes": 8388608, "thumbnail_pixels": 20000000, "namespaces": 8, "owner_entitlements": {"shows_per_month": {"free": 80, "vip": 300, "staff": 1000}, "piece_bytes": {"free": 16777216, "vip": 67108864, "staff": 268435456}, "distinct_tags": {"free": 64, "vip": 256, "staff": 1024}, "collections": {"free": 20, "vip": 100, "staff": 500}, "baas_projects": {"free": 5, "vip": 25, "staff": 100}}}, "idempotency": {"header": "Idempotency-Key", "optional": true, "recommended_for": ["show_create", "show_update", "piece_replace", "publication", "collection_create", "collection_attach", "runtime_identity_baas", "thumbnail_upload", "asset_upload"], "replay_window_seconds": 86400}, "routes": [{"id": "capabilities", "method": "GET", "path": "/api/v1/capabilities/", "authentication": "public"}, {"id": "identity", "method": "GET", "path": "/api/v1/me/", "authentication": "bearer", "scope": "identity:read"}, {"id": "show_list", "method": "GET", "path": "/api/v1/shows/", "authentication": "bearer", "scope": "shows:read"}, {"id": "show_create", "method": "POST", "path": "/api/v1/shows/", "authentication": "bearer", "scope": "shows:write", "content_type": "application/json", "request_example": {"title": "Tilt Garden", "desc": "An IMU-controlled visual study.", "prompt": "Describe the source architecture, interaction, fallback behavior, QA, and maintenance procedure in at least 80 characters.", "context": "tilt-garden", "category": "imu", "tags": ["imu", "interactive"], "cdns": ["https://cdn.jsdelivr.net/npm/three@0.179.1/build/three.module.js"], "esm": ["https://cdn.jsdelivr.net/npm/three@0.179.1/build/three.module.js"]}, "notes": "Always creates private=true, hidden=true, status=draft."}, {"id": "show_get", "method": "GET", "path": "/api/v1/shows/{show_id}/", "authentication": "bearer", "scope": "shows:read"}, {"id": "show_update", "method": "PATCH", "path": "/api/v1/shows/{show_id}/", "authentication": "bearer", "scope": "shows:write", "content_type": "application/json", "request_example": {"desc": "Updated description.", "tags": ["imu", "interactive"]}, "notes": "Any update returns a published Show to draft."}, {"id": "piece_replace", "method": "PUT", "path": "/api/v1/shows/{show_id}/pieces/", "authentication": "bearer", "scope": "shows:write", "content_type": "application/json", "request_example": {"pieces": [{"generic": "html", "name": "index.html", "raw": "<main id=\"app\"></main>"}, {"generic": "css", "name": "style.css", "raw": "#app { min-height: 100vh; }"}, {"generic": "js", "name": "app.js", "raw": "document.querySelector('#app').textContent = 'Ready';"}]}, "notes": "Authoritative source-tree replacement; compiled and unplug fields are never accepted."}, {"id": "publication", "method": "POST", "path": "/api/v1/shows/{show_id}/publication/", "authentication": "bearer", "scope": "shows:publish", "content_type": "application/json", "request_example": {"action": "publish", "confirm": true}, "notes": "The only route that can make a Show public; runs preflight and requires confirm=true."}, {"id": "collection_create", "method": "POST", "path": "/api/v1/collections/", "authentication": "bearer", "scope": "collections:write", "content_type": "application/json", "request_example": {"title": "IMU Experiments", "desc": "Motion and orientation Shows."}}, {"id": "collection_attach", "method": "PUT", "path": "/api/v1/collections/{collection_id}/shows/{show_id}/", "authentication": "bearer", "scope": "collections:write", "content_type": "application/json", "request_example": {}, "notes": "Both resources must belong to the credential owner."}, {"id": "runtime_identity_baas", "method": "POST", "path": "/api/v1/shows/{show_id}/baas/runtime-identity/", "authentication": "bearer", "scope": "baas:write", "content_type": "application/json", "request_example": {"namespaces": ["app-state"], "guest_write": false, "confirm_guest_write": false, "guest_ttl_days": 30}, "notes": "Provisions one private, isolated runtime-identity backend; anonymous guest writes are disabled in REST v1."}, {"id": "thumbnail_upload", "method": "POST", "path": "/api/v1/shows/{show_id}/thumbnail/", "authentication": "bearer", "scope": "assets:write", "content_type": "multipart/form-data", "request_example": {"file": "<JPEG, PNG, or WebP bytes>"}, "notes": "Pillow-verified cover image; 320x180 minimum, 20 megapixels and 8 MiB maximum; returns the Show to draft."}, {"id": "thumbnail_content", "method": "GET", "path": "/api/v1/shows/{show_id}/thumbnail/content/", "authentication": "bearer", "scope": "shows:read", "notes": "Streams an owned draft thumbnail without exposing its private storage name."}, {"id": "asset_upload", "method": "POST", "path": "/api/v1/shows/{show_id}/assets/", "authentication": "bearer", "scope": "assets:write", "content_type": "multipart/form-data", "request_example": {"file": "<bytes>", "mount_path": "images/hero.webp", "role": "attachment", "context": "hero image"}, "notes": "Byte upload only; remote URL fetching and executable assets are unsupported."}]}}