Bisque Presentations

{'type': 'object', 'required': ['title', 'content'], 'properties': {'icon': {'type': 'string', 'maxLength': 256, 'description': 'An emoji that stands for the page, e.g. 📊. The tab and Home Screen show icon_image, not this.'}, 'type': {'enum': ['html', 'markdown'], 'type': 'string', 'description': 'Default html.'}, 'state': {'type': 'object', 'properties': {'rules': {'type': 'array', 'items': {'type': 'object', 'required': ['path'], 'properties': {'path': {'type': 'string', 'description': "A slash path the rule covers, and everything below it; '' is the root. A trailing {self} names each person's own document under the prefix."}, 'read': {'enum': ['anyone', 'viewer', 'contributor', 'owner'], 'type': 'string'}, 'write': {'enum': ['viewer', 'contributor', 'owner'], 'type': 'string'}}, 'additionalProperties': False}}}, 'description': "Who may read and write which paths of the page's data, by the minimum role: viewer (can open), contributor (a data grant, separate from editing the page), owner. Absent means: everyone who can open reads, contributors and the owner write. Example poll: [{path:'votes',read:'viewer',write:'owner'},{path:'votes/{self}',write:'viewer'}].", 'additionalProperties': False}, 'title': {'type': 'string', 'maxLength': 200, 'minLength': 1, 'description': 'A short name, the way a document or app is named.'}, 'listed': {'type': 'boolean', 'description': 'Show it in listings (the org library, public discovery) rather than link-only. Default false.'}, 'content': {'type': 'string', 'description': 'The full document. For html: a complete page (styles and scripts inline; it runs in a sandboxed frame with no network). For markdown: the Markdown source.'}, 'audience': {'enum': ['owner', 'users', 'public'], 'type': 'string', 'description': 'Who can open the link. owner: only you. users: the people in share_with. public: anyone with the link.'}, 'icon_image': {'type': 'string', 'description': "The page's own icon: the favicon in the browser tab and the icon a phone puts on its Home Screen. A data URL: an SVG (data:image/svg+xml,<svg …>) or a base64 PNG, JPEG, WebP, or GIF, at most 512 KB, cropped to a square. An SVG must be self-contained (no links to other files, fonts, or stylesheets); draw shapes rather than text. Without one the page shows the Bisque icon."}, 'share_with': {'type': 'array', 'items': {'type': 'object', 'properties': {'uid': {'type': 'string', 'description': 'Their Bisque uid, if known.'}, 'role': {'enum': ['viewer', 'editor'], 'type': 'string', 'description': 'Default viewer.'}, 'email': {'type': 'string', 'description': "The person's account email."}}, 'additionalProperties': False}, 'maxItems': 100, 'description': 'People to grant access by email (or uid), with a role. [{ "email": "ana@acme.com", "role": "viewer" }]. viewer opens it; editor can also publish new content. Implies audience "users" when audience is omitted.'}, 'description': {'type': 'string', 'maxLength': 2000, 'description': 'One sentence saying what the page is; shown in listings.'}, 'capabilities': {'type': 'array', 'items': {'enum': ['state.read', 'state.write', 'events.emit', 'viewer.identity'], 'type': 'string'}, 'description': 'What the page may do at run time. state.read and state.write give it JSON documents at window.bisque.state (get, patch, list, subscribe); viewer.identity tells it who is viewing (window.bisque.viewer); events.emit lets it record typed Events. Omit for a page that only shows things.', 'uniqueItems': True}}, 'additionalProperties': False}

{'type': 'object', 'required': ['artifact_id', 'type', 'title', 'audience_mode', 'discoverability', 'published_version_id', 'url', 'version_id', 'publication_status'], 'properties': {'url': {'type': 'string', 'description': 'The viewer page.'}, 'icon': {'type': 'string'}, 'type': {'enum': ['html', 'markdown', 'presentation'], 'type': 'string'}, 'title': {'type': 'string'}, 'group_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'updated_at': {'type': 'string'}, 'version_id': {'type': 'string', 'description': 'The Version this call authored.'}, 'artifact_id': {'type': 'string'}, 'description': {'type': 'string'}, 'audience_mode': {'type': 'string', 'description': 'Who can open it: owner, users, org, or public.'}, 'icon_image_url': {'type': ['string', 'null'], 'description': 'The page icon set with icon_image; null for the Bisque icon.'}, 'version_number': {'type': 'integer'}, 'discoverability': {'enum': ['unlisted', 'listed'], 'type': 'string'}, 'organization_id': {'type': 'string'}, 'latest_version_id': {'type': 'string'}, 'publication_error': {'type': ['object', 'null'], 'properties': {'code': {'type': 'string'}, 'message': {'type': 'string'}}}, 'publication_status': {'enum': ['queued', 'processing', 'ready', 'failed'], 'type': 'string', 'description': 'ready means the URL serves this content now. queued or processing means it is still being prepared; call get_artifact to check. failed carries publication_error.'}, 'viewer_version_mode': {'enum': ['latest', 'pinned'], 'type': 'string'}, 'published_version_id': {'type': ['string', 'null'], 'description': 'The Version viewers see; null until a publication is ready.'}}}

{'type': 'object', 'required': ['artifact_id', 'body'], 'properties': {'body': {'type': 'string', 'maxLength': 4000, 'minLength': 1, 'description': 'Markdown subset: bold, italic, code, links, lists.'}, 'anchor': {'type': 'object', 'description': 'Optional pin. { kind: "page", slideId, slideIndex, timeSec } for a slide or time; { kind: "element", selector, xFrac, yFrac, snapshot: { tag, text }, slideId, slideIndex, cueTarget, timeSec } for an element; { kind: "text", quote, prefix, suffix, selector, slideId, slideIndex } for a passage.'}, 'artifact_id': {'type': 'string', 'pattern': '^art_[a-zA-Z0-9]+$', 'description': 'The Artifact id (art_…).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['thread_id', 'artifact_id', 'status', 'anchor', 'version_number', 'preview', 'message_count', 'agent_activated', 'created_by', 'created_at', 'last_message_at', 'messages'], 'properties': {'anchor': {'type': 'object', 'description': 'Where the thread is pinned: kind element (selector, snapshot, slide), text (quote), or page.'}, 'status': {'enum': ['open', 'resolved'], 'type': 'string'}, 'preview': {'type': 'string'}, 'mentions': {'type': 'array', 'items': {'type': 'string'}}, 'messages': {'type': 'array', 'items': {'type': 'object', 'required': ['message_id', 'thread_id', 'author', 'body', 'created_at'], 'properties': {'body': {'type': 'string'}, 'author': {'type': 'object', 'description': 'Who wrote it: { kind: "user", uid, name, handle, avatarUrl } or { kind: "agent", principal, name, via }.'}, 'mentions': {'type': 'array', 'items': {'type': 'string'}}, 'edited_at': {'type': ['string', 'null']}, 'reactions': {'type': 'object'}, 'thread_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'message_id': {'type': 'string'}, 'artifact_id': {'type': 'string'}, 'attachments': {'type': 'array', 'items': {'type': 'object'}}}}}, 'thread_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'created_by': {'type': 'object', 'description': 'Who wrote it: { kind: "user", uid, name, handle, avatarUrl } or { kind: "agent", principal, name, via }.'}, 'updated_at': {'type': 'string'}, 'version_id': {'type': 'string'}, 'artifact_id': {'type': 'string'}, 'resolved_at': {'type': ['string', 'null']}, 'participants': {'type': 'array', 'items': {'type': 'string'}}, 'message_count': {'type': 'integer'}, 'version_number': {'type': 'integer'}, 'agent_activated': {'type': 'boolean', 'description': 'True once someone mentioned the agent; only then may the agent reply or resolve.'}, 'last_message_at': {'type': 'string'}, 'root_message_id': {'type': 'string'}}}

{'type': 'object', 'required': ['indexHtml'], 'properties': {'slug': {'type': 'string', 'description': 'URL slug; defaults to a slugified title.'}, 'audio': {'type': 'array', 'items': {'type': 'object'}, 'description': 'Optional. One entry per slide YOU narrated, from the JSON `bisque-voice` prints — word timings, duration, size and digest. Send it and your audio is used (free, unlimited, any OS); leave it out and the server narrates. The response says how many slides speak, and names any that published silent.'}, 'title': {'type': 'string', 'maxLength': 200, 'description': 'Display title for the watch page and listings. Omit to use the title parsed from the document.'}, 'assets': {'type': 'array', 'items': {'type': 'object', 'required': ['path', 'url'], 'properties': {'url': {'type': 'string', 'description': 'Public https source to fetch the bytes from (e.g. a fonts.gstatic.com woff2 URL, an image URL).'}, 'path': {'type': 'string', 'description': 'Bundle-relative path your HTML references, e.g. assets/fonts/inter-600.woff2. Must start with assets/.'}, 'sha256': {'type': 'string', 'pattern': '^sha256:[a-fA-F0-9]{64}$', 'description': 'Optional integrity pin — the create fails if the fetched bytes hash differently.'}}, 'additionalProperties': False}, 'maxItems': 20, 'description': 'Files the document references relative to itself — fonts, images, Lottie/Rive animations, sound-effect audio, video clips. The SERVER fetches each https url at create time and stores it in the bundle, so reference `assets/...` paths in your HTML and list the sources here instead of inlining base64. 10MB per asset, 30MB total.'}, 'dryRun': {'type': 'boolean', 'default': False, 'description': 'Sandbox: run every check a real create runs (format, slug and org conflicts, tier cap, credit preflight) and write nothing. The reply has status "validated" and the webUrl a real create would publish at. Use it to test an integration without touching the channel.'}, 'handle': {'type': 'string', 'description': 'Publish under a specific channel handle you own.'}, 'voiceId': {'type': 'string', 'description': 'Narration voice. ElevenLabs: a bare id or cloud:<id>. Self-hosted Kokoro: kokoro:<id> (e.g. kokoro:af_heart); local:<id> is accepted as a synonym. Omit to use the voice saved on the account (bisque.cloud/account), falling back to the server default.'}, 'designMd': {'type': 'string', 'description': 'Design frontmatter mapped to theme tokens.'}, 'madeWith': {'type': 'array', 'items': {'type': 'string', 'maxLength': 80}, 'maxItems': 8, 'description': 'Credit the models that made this: the model you are running as, and the narration engine or voice service if you know it — e.g. ["Claude Opus 5", "Kokoro af_heart"]. Shown to viewers in the watch page\'s ⋯ menu. Send it on every create; omitting it keeps whatever a previous publish recorded.'}, 'contextMd': {'type': 'string', 'description': 'Shared-with-viewer context.md.'}, 'indexHtml': {'type': 'string', 'maxLength': 4194304, 'minLength': 1, 'description': 'Full html-presentation/v1 document (the presentation-format meta gate applies).'}, 'visibility': {'enum': ['private', 'unlisted', 'public'], 'type': 'string', 'default': 'unlisted', 'description': 'unlisted (the default) is shareable by link and plays in chat-embedded players; private requires the owner to sign in, so an inline chat player shows a sign-in wall instead of playing — choose private only when the user asked for it.'}, 'speechSpeed': {'type': 'number', 'description': 'Narration speed multiplier passed to the voice. Omit for the server default.'}, 'presentationId': {'type': 'string', 'maxLength': 120, 'minLength': 1, 'description': 'Stable id for idempotent re-creates; defaults to slug-<hash(userId:slug)>.'}, 'voiceStability': {'type': 'number', 'description': 'Voice stability setting passed to the narration engine. Omit for the server default.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['presentationId', 'webUrl', 'status', 'statusUrl', 'narration'], 'properties': {'status': {'enum': ['ready', 'queued'], 'type': 'string', 'description': 'ready = nothing needed narration; queued = narration runs in the background — poll get_presentation_status.'}, 'webUrl': {'type': 'string', 'description': 'Shareable watch URL (live once status is ready).'}, 'narration': {'type': 'object', 'required': ['narratedSlides', 'totalSlides', 'estimatedChars'], 'properties': {'totalSlides': {'type': 'integer'}, 'estimatedChars': {'type': 'integer'}, 'narratedSlides': {'type': 'integer'}}}, 'statusUrl': {'type': 'string'}, 'presentationId': {'type': 'string'}}}

{'type': 'object', 'required': ['artifact_id'], 'properties': {'artifact_id': {'type': 'string', 'pattern': '^art_[a-zA-Z0-9]+$', 'description': 'The Artifact id (art_…).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['artifact_id', 'deleted'], 'properties': {'deleted': {'type': 'boolean'}, 'artifact_id': {'type': 'string'}, 'already_deleted': {'type': 'boolean'}}}

{'type': 'object', 'required': ['artifact_id'], 'properties': {'artifact_id': {'type': 'string', 'pattern': '^art_[a-zA-Z0-9]+$', 'description': 'The Artifact id (art_…).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['artifact_id', 'type', 'title', 'audience_mode', 'discoverability', 'published_version_id', 'url'], 'properties': {'url': {'type': 'string', 'description': 'The viewer page.'}, 'icon': {'type': 'string'}, 'type': {'enum': ['html', 'markdown', 'presentation'], 'type': 'string'}, 'title': {'type': 'string'}, 'group_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'updated_at': {'type': 'string'}, 'artifact_id': {'type': 'string'}, 'description': {'type': 'string'}, 'audience_mode': {'type': 'string', 'description': 'Who can open it: owner, users, org, or public.'}, 'icon_image_url': {'type': ['string', 'null'], 'description': 'The page icon set with icon_image; null for the Bisque icon.'}, 'discoverability': {'enum': ['unlisted', 'listed'], 'type': 'string'}, 'organization_id': {'type': 'string'}, 'latest_version_id': {'type': 'string'}, 'viewer_version_mode': {'enum': ['latest', 'pinned'], 'type': 'string'}, 'published_version_id': {'type': ['string', 'null'], 'description': 'The Version viewers see; null until a publication is ready.'}}}

{'type': 'object', 'required': ['artifact_id', 'thread_id'], 'properties': {'thread_id': {'type': 'string', 'pattern': '^thr_[a-zA-Z0-9]+$', 'description': 'The thread id (thr_…).'}, 'artifact_id': {'type': 'string', 'pattern': '^art_[a-zA-Z0-9]+$', 'description': 'The Artifact id (art_…).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['thread_id', 'artifact_id', 'status', 'anchor', 'version_number', 'preview', 'message_count', 'agent_activated', 'created_by', 'created_at', 'last_message_at', 'messages'], 'properties': {'anchor': {'type': 'object', 'description': 'Where the thread is pinned: kind element (selector, snapshot, slide), text (quote), or page.'}, 'status': {'enum': ['open', 'resolved'], 'type': 'string'}, 'preview': {'type': 'string'}, 'mentions': {'type': 'array', 'items': {'type': 'string'}}, 'messages': {'type': 'array', 'items': {'type': 'object', 'required': ['message_id', 'thread_id', 'author', 'body', 'created_at'], 'properties': {'body': {'type': 'string'}, 'author': {'type': 'object', 'description': 'Who wrote it: { kind: "user", uid, name, handle, avatarUrl } or { kind: "agent", principal, name, via }.'}, 'mentions': {'type': 'array', 'items': {'type': 'string'}}, 'edited_at': {'type': ['string', 'null']}, 'reactions': {'type': 'object'}, 'thread_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'message_id': {'type': 'string'}, 'artifact_id': {'type': 'string'}, 'attachments': {'type': 'array', 'items': {'type': 'object'}}}}}, 'thread_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'created_by': {'type': 'object', 'description': 'Who wrote it: { kind: "user", uid, name, handle, avatarUrl } or { kind: "agent", principal, name, via }.'}, 'updated_at': {'type': 'string'}, 'version_id': {'type': 'string'}, 'artifact_id': {'type': 'string'}, 'resolved_at': {'type': ['string', 'null']}, 'participants': {'type': 'array', 'items': {'type': 'string'}}, 'message_count': {'type': 'integer'}, 'version_number': {'type': 'integer'}, 'agent_activated': {'type': 'boolean', 'description': 'True once someone mentioned the agent; only then may the agent reply or resolve.'}, 'last_message_at': {'type': 'string'}, 'root_message_id': {'type': 'string'}}}

{'type': 'object', 'required': ['presentationId'], 'properties': {'presentationId': {'type': 'string', 'maxLength': 120, 'minLength': 1, 'description': 'The presentationId whose view counts and survey responses you want.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['presentationId', 'title', 'slug', 'viewCount', 'likeCount', 'completedCount', 'uniqueViewers', 'anonViewers', 'completionRate', 'slideReach', 'sources', 'orgDomains'], 'properties': {'slug': {'type': 'string'}, 'title': {'type': 'string'}, 'webUrl': {'type': 'string'}, 'sources': {'type': 'object', 'description': 'Traffic source → view count.'}, 'likeCount': {'type': 'integer'}, 'viewCount': {'type': 'integer'}, 'orgDomains': {'type': 'array', 'items': {'type': 'object', 'required': ['domain', 'viewers'], 'properties': {'domain': {'type': 'string'}, 'viewers': {'type': 'integer'}}}, 'description': 'Organization email domains of signed-in viewers (personal providers filtered), sorted desc.'}, 'slideReach': {'type': 'array', 'items': {'type': 'object', 'required': ['slideIndex', 'reached'], 'properties': {'reached': {'type': 'integer'}, 'slideIndex': {'type': 'integer'}}}, 'description': 'Retention funnel ordered by slide index.'}, 'anonViewers': {'type': 'integer'}, 'uniqueViewers': {'type': 'integer', 'description': 'Distinct signed-in viewers.'}, 'completedCount': {'type': 'integer'}, 'completionRate': {'type': ['number', 'null'], 'description': 'completedCount / viewCount, 0..1; null when no views.'}, 'presentationId': {'type': 'string'}}}

{'type': 'object', 'properties': {'url': {'type': 'string', 'maxLength': 2000, 'description': 'Watch URL, e.g. https://bisque.today/p/{handle}/{slug}. Provide this OR handle + slug.'}, 'slug': {'type': 'string', 'maxLength': 80, 'description': 'URL slug, the last path segment of the watch URL. Use with handle, or pass url instead.'}, 'handle': {'type': 'string', 'maxLength': 80, 'description': 'Channel handle (leading @ allowed).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['presentationId', 'title', 'handle', 'slug', 'webUrl', 'visibility', 'transcript', 'transcriptTruncatedSlides', 'contextMd', 'contextTruncated'], 'properties': {'slug': {'type': 'string'}, 'title': {'type': 'string'}, 'handle': {'type': 'string'}, 'webUrl': {'type': 'string'}, 'contextMd': {'type': ['string', 'null'], 'description': "The bundle's context.md (shared agent-facing background); null when the presentation ships none."}, 'transcript': {'type': 'array', 'items': {'type': 'object', 'required': ['slideIndex', 'startSec', 'title', 'text'], 'properties': {'text': {'type': 'string'}, 'title': {'type': 'string'}, 'startSec': {'type': 'number'}, 'slideIndex': {'type': 'integer'}}}, 'description': 'Per-slide narration, ordered by slide index.'}, 'visibility': {'type': 'string'}, 'description': {'type': ['string', 'null']}, 'publishedAt': {'type': ['string', 'null'], 'description': 'ISO 8601, null when unknown.'}, 'presentationId': {'type': 'string'}, 'contextTruncated': {'type': 'boolean'}, 'transcriptTruncatedSlides': {'type': 'integer', 'description': 'Content slides the size-capped transcript dropped; 0 = complete.'}}}

{'type': 'object', 'properties': {}, 'additionalProperties': False}

{'type': 'object', 'required': ['format', 'spec'], 'properties': {'spec': {'type': 'string', 'description': 'The full authoring recipe + format contract, markdown.'}, 'format': {'type': 'string'}}}

{'type': 'object', 'required': ['presentationId'], 'properties': {'presentationId': {'type': 'string', 'maxLength': 120, 'minLength': 1, 'description': 'The presentationId returned by create_presentation or publish_narrated_presentation.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['presentationId', 'publishStatus', 'ready'], 'properties': {'ready': {'type': 'boolean', 'description': 'True once the presentation is viewable.'}, 'webUrl': {'type': 'string', 'description': 'Shareable watch URL.'}, 'narration': {'type': 'object', 'description': 'Narration progress: status (complete | partial | failed | …) and per-slide errors when partial/failed.'}, 'visibility': {'type': 'string'}, 'publishStatus': {'type': 'string'}, 'presentationId': {'type': 'string'}}}

{'type': 'object', 'properties': {'type': {'enum': ['html', 'markdown', 'presentation'], 'type': 'string', 'description': 'Only this type.'}, 'limit': {'type': 'integer', 'maximum': 100, 'minimum': 1, 'description': 'Page size, default 25.'}, 'scope': {'enum': ['owned', 'shared', 'all'], 'type': 'string', 'description': 'Default owned.'}, 'cursor': {'type': 'string', 'description': 'next_cursor from a prior page.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['items', 'next_cursor'], 'properties': {'items': {'type': 'array', 'items': {'type': 'object', 'required': ['artifact_id', 'type', 'title', 'audience_mode', 'discoverability', 'published_version_id', 'url'], 'properties': {'url': {'type': 'string', 'description': 'The viewer page.'}, 'icon': {'type': 'string'}, 'type': {'enum': ['html', 'markdown', 'presentation'], 'type': 'string'}, 'title': {'type': 'string'}, 'group_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'updated_at': {'type': 'string'}, 'artifact_id': {'type': 'string'}, 'description': {'type': 'string'}, 'audience_mode': {'type': 'string', 'description': 'Who can open it: owner, users, org, or public.'}, 'icon_image_url': {'type': ['string', 'null'], 'description': 'The page icon set with icon_image; null for the Bisque icon.'}, 'discoverability': {'enum': ['unlisted', 'listed'], 'type': 'string'}, 'organization_id': {'type': 'string'}, 'latest_version_id': {'type': 'string'}, 'viewer_version_mode': {'enum': ['latest', 'pinned'], 'type': 'string'}, 'published_version_id': {'type': ['string', 'null'], 'description': 'The Version viewers see; null until a publication is ready.'}}}}, 'next_cursor': {'type': ['string', 'null']}}}

{'type': 'object', 'required': ['artifact_id'], 'properties': {'after': {'type': 'string', 'description': 'RFC 3339 date-time; only threads with activity after it.'}, 'cursor': {'type': 'string', 'description': 'next_cursor from a prior page.'}, 'status': {'enum': ['open', 'resolved', 'all'], 'type': 'string', 'description': 'Default open.'}, 'artifact_id': {'type': 'string', 'pattern': '^art_[a-zA-Z0-9]+$', 'description': 'The Artifact id (art_…).'}, 'activated_only': {'type': 'boolean', 'description': 'Only threads where the agent was mentioned.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['artifact_id', 'items', 'next_cursor'], 'properties': {'items': {'type': 'array', 'items': {'type': 'object', 'required': ['thread_id', 'artifact_id', 'status', 'anchor', 'version_number', 'preview', 'message_count', 'agent_activated', 'created_by', 'created_at', 'last_message_at'], 'properties': {'anchor': {'type': 'object', 'description': 'Where the thread is pinned: kind element (selector, snapshot, slide), text (quote), or page.'}, 'status': {'enum': ['open', 'resolved'], 'type': 'string'}, 'preview': {'type': 'string'}, 'mentions': {'type': 'array', 'items': {'type': 'string'}}, 'thread_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'created_by': {'type': 'object', 'description': 'Who wrote it: { kind: "user", uid, name, handle, avatarUrl } or { kind: "agent", principal, name, via }.'}, 'updated_at': {'type': 'string'}, 'version_id': {'type': 'string'}, 'artifact_id': {'type': 'string'}, 'resolved_at': {'type': ['string', 'null']}, 'participants': {'type': 'array', 'items': {'type': 'string'}}, 'message_count': {'type': 'integer'}, 'version_number': {'type': 'integer'}, 'agent_activated': {'type': 'boolean', 'description': 'True once someone mentioned the agent; only then may the agent reply or resolve.'}, 'last_message_at': {'type': 'string'}, 'root_message_id': {'type': 'string'}}}}, 'artifact_id': {'type': 'string'}, 'next_cursor': {'type': ['string', 'null']}}}

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'default': 50, 'maximum': 100, 'minimum': 1, 'description': 'Maximum number of presentations to return per page.'}, 'cursor': {'type': 'string', 'description': 'The `nextCursor` from a previous call, to read the page after that one. Omit it to start at the newest presentation.'}, 'visibility': {'enum': ['private', 'unlisted', 'public'], 'type': 'string', 'description': 'Return only presentations with this visibility. Omit to return every one of them.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['presentations', 'nextCursor'], 'properties': {'nextCursor': {'type': ['string', 'null'], 'description': 'Pass this back as `cursor` for the next page. Null when this page is the last one.'}, 'presentations': {'type': 'array', 'items': {'type': 'object', 'required': ['presentationId', 'title', 'slug', 'visibility', 'publishStatus', 'webUrl'], 'properties': {'slug': {'type': 'string'}, 'title': {'type': 'string'}, 'webUrl': {'type': 'string'}, 'createdAt': {'type': ['string', 'null'], 'description': 'ISO 8601, null when unknown.'}, 'visibility': {'type': 'string'}, 'publishStatus': {'type': 'string'}, 'presentationId': {'type': 'string'}}}, 'description': 'Newest first.'}}}

{'type': 'object', 'required': ['indexHtml'], 'properties': {'slug': {'type': 'string', 'description': 'URL slug; defaults to a slugified title.'}, 'audio': {'type': 'array', 'items': {'type': 'object', 'required': ['words', 'durationMs', 'size', 'hash'], 'properties': {'hash': {'type': 'string', 'pattern': '^sha256:[a-fA-F0-9]{64}$', 'description': 'sha256:<64 hex> digest of the MP3 bytes.'}, 'size': {'type': 'integer', 'minimum': 1, 'description': 'Encoded MP3 byte count.'}, 'exact': {'type': 'boolean', 'description': "Pass through bisque-voice's `exact`. False means timings were distributed proportionally; reported back as a warning."}, 'speed': {'type': 'number'}, 'voice': {'type': 'string'}, 'words': {'type': 'array', 'items': {'type': 'object', 'required': ['word', 'start', 'end'], 'properties': {'end': {'type': 'number'}, 'word': {'type': 'string'}, 'start': {'type': 'number'}}, 'additionalProperties': False}, 'description': "Word timings in SECONDS, 1:1 with the narration's whitespace tokens. Rejected if the count differs — cue markers index this array by position, so a mismatch silently misplaces every later cue."}, 'chunks': {'type': 'integer'}, 'slideKey': {'type': 'string', 'description': 'Manifest slide key, e.g. slide-00. Use this or slideIndex.'}, 'durationMs': {'type': 'integer', 'minimum': 1, 'description': 'Audio duration in whole milliseconds.'}, 'slideIndex': {'type': 'integer', 'minimum': 0, 'description': '0-based index of the slide in the document. Use this or slideKey.'}, 'contentType': {'type': 'string', 'const': 'audio/mpeg', 'description': 'Rejected unless audio/mpeg — a WAV would publish mislabelled.'}}, 'additionalProperties': False}, 'description': 'One entry per slide you synthesized, from the JSON `bisque-voice` prints on stdout. `words`, `durationMs`, `size` and `hash` map across verbatim. Optional: omit a slide (or the whole array) and its audio carries forward from the previous publish if the narration text is unchanged — otherwise that slide publishes silent and is listed in `staleSlides`. A FIRST publish with nothing to carry forward is rejected.'}, 'title': {'type': 'string', 'maxLength': 200, 'description': 'Display title for the watch page and listings. Omit to use the title parsed from the document.'}, 'assets': {'type': 'array', 'items': {'type': 'object', 'required': ['path', 'size', 'hash'], 'properties': {'hash': {'type': 'string', 'description': 'sha256:<64 hex chars> of those bytes, prefix included.'}, 'path': {'type': 'string', 'description': 'Bundle-relative path, e.g. assets/fonts/inter.woff2. Must start with `assets/`; no absolute paths and no `..` segments.'}, 'size': {'type': 'integer', 'minimum': 0, 'description': 'Byte length of the file you are about to upload.'}, 'contentType': {'type': 'string', 'description': 'Ignored. The server derives the content type from the file extension so one map decides how every asset is served.'}}, 'additionalProperties': False}, 'description': 'Files the document references relative to itself — fonts, images, SVG, Lottie, Rive, bundled audio cues. html-presentation/v1 requires these to be self-hosted, so a presentation that renders locally is broken once published unless they travel with it. Each gets an upload URL back alongside the MP3s; PUT them the same way. Paths must be under `assets/` — the server owns index.html, presentation.json and context.md, and the manifest owns audio/. Omit for a presentation that references nothing.'}, 'handle': {'type': 'string', 'description': 'Publish under a specific channel handle you own.'}, 'voiceId': {'type': 'string', 'description': 'Records what actually spoke, e.g. kokoro:af_heart for a locally synthesized Kokoro voice. No audio is generated server-side.'}, 'designMd': {'type': 'string', 'description': 'Design frontmatter mapped to theme tokens.'}, 'madeWith': {'type': 'array', 'items': {'type': 'string', 'maxLength': 80}, 'maxItems': 8, 'description': 'Credit the models that made this: the model you are running as, and the engine that synthesized the audio you are uploading — e.g. ["Claude Opus 5", "Kokoro af_heart"]. Shown to viewers in the watch page\'s ⋯ menu. Send it on every publish; omitting it keeps whatever a previous publish recorded.'}, 'contextMd': {'type': 'string', 'description': 'Shared-with-viewer context.md.'}, 'indexHtml': {'type': 'string', 'maxLength': 4194304, 'minLength': 1, 'description': 'Full html-presentation/v1 document (the presentation-format meta gate applies).'}, 'visibility': {'enum': ['private', 'unlisted', 'public'], 'type': 'string', 'default': 'unlisted', 'description': 'unlisted (the default) is shareable by link and plays in chat-embedded players; private requires the owner to sign in, so an inline chat player shows a sign-in wall instead of playing — choose private only when the user asked for it.'}, 'speechSpeed': {'type': 'number', 'description': 'Must match the speed you synthesized at — it is part of the audio cache key, so changing it on a re-publish makes every slide stale instead of carrying forward.'}, 'presentationId': {'type': 'string', 'maxLength': 120, 'minLength': 1, 'description': 'Stable id for idempotent re-publishes; defaults to slug-<hash(userId:slug)>.'}, 'voiceStability': {'type': 'number', 'description': 'Records the stability setting you synthesized at. No audio is generated server-side.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['presentationId', 'webUrl', 'uploadUrls', 'completeUrl', 'publishId', 'files', 'reused', 'synthesized', 'staleSlides', 'warnings'], 'properties': {'files': {'type': 'array', 'items': {'type': 'object'}, 'description': "Echo back verbatim as the complete call's `files`."}, 'reused': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Slide keys whose audio carried forward — no upload.'}, 'webUrl': {'type': 'string', 'description': 'Shareable watch URL.'}, 'warnings': {'type': 'array', 'items': {'type': 'string'}}, 'publishId': {'type': 'string'}, 'uploadUrls': {'type': 'array', 'items': {'type': 'object', 'required': ['path', 'url', 'method', 'headers'], 'properties': {'url': {'type': 'string'}, 'path': {'type': 'string'}, 'method': {'enum': ['PUT'], 'type': 'string'}, 'headers': {'type': 'object'}}}, 'description': 'One pre-signed PUT per file to upload.'}, 'completeUrl': {'type': 'string', 'description': 'POST here after every PUT, echoing `files` back verbatim.'}, 'staleSlides': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Narrated slide keys that will publish SILENT — synthesize exactly these and publish again.'}, 'synthesized': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Slide keys this request supplied audio for.'}, 'presentationId': {'type': 'string'}}}

{'type': 'object', 'required': ['artifact_id', 'thread_id', 'body'], 'properties': {'body': {'type': 'string', 'maxLength': 4000, 'minLength': 1}, 'thread_id': {'type': 'string', 'pattern': '^thr_[a-zA-Z0-9]+$', 'description': 'The thread id (thr_…).'}, 'artifact_id': {'type': 'string', 'pattern': '^art_[a-zA-Z0-9]+$', 'description': 'The Artifact id (art_…).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['message_id', 'thread_id', 'author', 'body', 'created_at'], 'properties': {'body': {'type': 'string'}, 'author': {'type': 'object', 'description': 'Who wrote it: { kind: "user", uid, name, handle, avatarUrl } or { kind: "agent", principal, name, via }.'}, 'mentions': {'type': 'array', 'items': {'type': 'string'}}, 'edited_at': {'type': ['string', 'null']}, 'reactions': {'type': 'object'}, 'thread_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'message_id': {'type': 'string'}, 'artifact_id': {'type': 'string'}, 'attachments': {'type': 'array', 'items': {'type': 'object'}}}}

{'type': 'object', 'required': ['artifact_id', 'thread_id', 'resolved'], 'properties': {'resolved': {'type': 'boolean'}, 'thread_id': {'type': 'string', 'pattern': '^thr_[a-zA-Z0-9]+$', 'description': 'The thread id (thr_…).'}, 'artifact_id': {'type': 'string', 'pattern': '^art_[a-zA-Z0-9]+$', 'description': 'The Artifact id (art_…).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['thread_id', 'artifact_id', 'status', 'anchor', 'version_number', 'preview', 'message_count', 'agent_activated', 'created_by', 'created_at', 'last_message_at'], 'properties': {'anchor': {'type': 'object', 'description': 'Where the thread is pinned: kind element (selector, snapshot, slide), text (quote), or page.'}, 'status': {'enum': ['open', 'resolved'], 'type': 'string'}, 'preview': {'type': 'string'}, 'mentions': {'type': 'array', 'items': {'type': 'string'}}, 'thread_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'created_by': {'type': 'object', 'description': 'Who wrote it: { kind: "user", uid, name, handle, avatarUrl } or { kind: "agent", principal, name, via }.'}, 'updated_at': {'type': 'string'}, 'version_id': {'type': 'string'}, 'artifact_id': {'type': 'string'}, 'resolved_at': {'type': ['string', 'null']}, 'participants': {'type': 'array', 'items': {'type': 'string'}}, 'message_count': {'type': 'integer'}, 'version_number': {'type': 'integer'}, 'agent_activated': {'type': 'boolean', 'description': 'True once someone mentioned the agent; only then may the agent reply or resolve.'}, 'last_message_at': {'type': 'string'}, 'root_message_id': {'type': 'string'}}}

{'type': 'object', 'required': ['artifact_id', 'audience'], 'properties': {'listed': {'type': 'boolean', 'description': 'Show it in listings (the org library, public discovery) rather than link-only. Default false.'}, 'audience': {'enum': ['owner', 'users', 'public'], 'type': 'string', 'description': 'Who can open the link. owner: only you. users: the people in share_with. public: anyone with the link.'}, 'share_with': {'type': 'array', 'items': {'type': 'object', 'properties': {'uid': {'type': 'string', 'description': 'Their Bisque uid, if known.'}, 'role': {'enum': ['viewer', 'editor'], 'type': 'string', 'description': 'Default viewer.'}, 'email': {'type': 'string', 'description': "The person's account email."}}, 'additionalProperties': False}, 'maxItems': 100, 'description': 'People to grant access by email (or uid), with a role. [{ "email": "ana@acme.com", "role": "viewer" }]. viewer opens it; editor can also publish new content. Implies audience "users" when audience is omitted.'}, 'artifact_id': {'type': 'string', 'pattern': '^art_[a-zA-Z0-9]+$', 'description': 'The Artifact id (art_…).'}, 'delete_threads': {'type': 'boolean', 'description': 'Allow going public on an Artifact that has comment threads, deleting them.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['artifact_id', 'audience_mode', 'discoverability', 'grants', 'url'], 'properties': {'url': {'type': 'string'}, 'grants': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': ['string', 'null']}, 'role': {'enum': ['viewer', 'editor'], 'type': 'string'}, 'email': {'type': ['string', 'null']}, 'principal': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'type': {'type': 'string'}}}}}}, 'artifact_id': {'type': 'string'}, 'audience_mode': {'type': 'string'}, 'discoverability': {'enum': ['unlisted', 'listed'], 'type': 'string'}, 'public_sharing_allowed': {'type': 'boolean'}, 'external_sharing_allowed': {'type': 'boolean'}}}

{'type': 'object', 'required': ['artifact_id'], 'properties': {'icon': {'type': ['string', 'null'], 'maxLength': 256, 'description': 'null clears it.'}, 'state': {'type': 'object', 'properties': {'rules': {'type': 'array', 'items': {'type': 'object', 'required': ['path'], 'properties': {'path': {'type': 'string', 'description': "A slash path the rule covers, and everything below it; '' is the root. A trailing {self} names each person's own document under the prefix."}, 'read': {'enum': ['anyone', 'viewer', 'contributor', 'owner'], 'type': 'string'}, 'write': {'enum': ['viewer', 'contributor', 'owner'], 'type': 'string'}}, 'additionalProperties': False}}}, 'description': "Who may read and write which paths of the page's data, by the minimum role: viewer (can open), contributor (a data grant, separate from editing the page), owner. Absent means: everyone who can open reads, contributors and the owner write. Example poll: [{path:'votes',read:'viewer',write:'owner'},{path:'votes/{self}',write:'viewer'}].", 'additionalProperties': False}, 'title': {'type': 'string', 'maxLength': 200, 'minLength': 1}, 'content': {'type': 'string', 'description': 'The complete new document, same type as before.'}, 'icon_image': {'type': ['string', 'null'], 'description': "The page's own icon: the favicon in the browser tab and the icon a phone puts on its Home Screen. A data URL: an SVG (data:image/svg+xml,<svg …>) or a base64 PNG, JPEG, WebP, or GIF, at most 512 KB, cropped to a square. An SVG must be self-contained (no links to other files, fonts, or stylesheets); draw shapes rather than text. Without one the page shows the Bisque icon. null goes back to the Bisque icon."}, 'artifact_id': {'type': 'string', 'pattern': '^art_[a-zA-Z0-9]+$', 'description': 'The Artifact id (art_…).'}, 'description': {'type': ['string', 'null'], 'maxLength': 2000, 'description': 'null clears it.'}, 'capabilities': {'type': 'array', 'items': {'enum': ['state.read', 'state.write', 'events.emit', 'viewer.identity'], 'type': 'string'}, 'description': 'What the page may do at run time. state.read and state.write give it JSON documents at window.bisque.state (get, patch, list, subscribe); viewer.identity tells it who is viewing (window.bisque.viewer); events.emit lets it record typed Events. Omit for a page that only shows things.', 'uniqueItems': True}}, 'additionalProperties': False}

{'type': 'object', 'required': ['artifact_id', 'type', 'title', 'audience_mode', 'discoverability', 'published_version_id', 'url'], 'properties': {'url': {'type': 'string', 'description': 'The viewer page.'}, 'icon': {'type': 'string'}, 'type': {'enum': ['html', 'markdown', 'presentation'], 'type': 'string'}, 'title': {'type': 'string'}, 'group_id': {'type': 'string'}, 'created_at': {'type': 'string'}, 'updated_at': {'type': 'string'}, 'version_id': {'type': 'string', 'description': 'The Version this call authored.'}, 'artifact_id': {'type': 'string'}, 'description': {'type': 'string'}, 'audience_mode': {'type': 'string', 'description': 'Who can open it: owner, users, org, or public.'}, 'icon_image_url': {'type': ['string', 'null'], 'description': 'The page icon set with icon_image; null for the Bisque icon.'}, 'version_number': {'type': 'integer'}, 'discoverability': {'enum': ['unlisted', 'listed'], 'type': 'string'}, 'organization_id': {'type': 'string'}, 'latest_version_id': {'type': 'string'}, 'publication_error': {'type': ['object', 'null'], 'properties': {'code': {'type': 'string'}, 'message': {'type': 'string'}}}, 'publication_status': {'enum': ['queued', 'processing', 'ready', 'failed'], 'type': 'string', 'description': 'ready means the URL serves this content now. queued or processing means it is still being prepared; call get_artifact to check. failed carries publication_error.'}, 'viewer_version_mode': {'enum': ['latest', 'pinned'], 'type': 'string'}, 'published_version_id': {'type': ['string', 'null'], 'description': 'The Version viewers see; null until a publication is ready.'}}}

{'type': 'object', 'properties': {'handle': {'type': 'string', 'maxLength': 30, 'minLength': 3, 'description': 'Which of your channel handles to update; defaults to your default username.'}, 'image_url': {'type': 'string', 'maxLength': 2000, 'minLength': 1, 'description': 'https URL of the avatar image (any common format, ≤10 MB).'}, 'description': {'type': 'string', 'maxLength': 160, 'description': "What the channel publishes, in the owner's words. Empty clears it."}}, 'additionalProperties': False}

{'type': 'object', 'required': ['handle', 'channelUrl', 'updated'], 'properties': {'failed': {'type': 'array', 'items': {'type': 'object', 'required': ['field', 'reason'], 'properties': {'field': {'type': 'string'}, 'reason': {'type': 'string'}}}, 'description': 'Fields that did not apply, each with the reason. A field listed here left the channel unchanged; the ones in updated still took effect.'}, 'handle': {'type': 'string'}, 'updated': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Field names that were written.'}, 'channelUrl': {'type': 'string', 'description': 'Public channel page carrying the update.'}, 'description': {'type': ['string', 'null'], 'description': 'The stored line, or null when the write cleared it.'}}}