{"apiVersion":"v1","capabilityContractVersion":"2026-07-22.3","lastUpdated":"2026-07-22T23:45:00Z","documentation":"https://readbeckon.com/publishers","format":"https://readbeckon.com/format","authentication":{"scheme":"Bearer","tokenPrefix":"bkn_live_","storage":"Secret manager only; never a browser, .beckon package, prompt, commit, log, or screenshot.","currentScope":"All active publishing keys have the same publisher authority for their owning Beckon account; per-key scopes are not yet available."},"allowed":["Claim an unused publicationId for the owning account","Create, inspect, and discard mutable private preview workspaces","Replace a workspace candidate through generation-guarded signed uploads","Read structured browser edits and reconcile them into publisher source","Promote one approved workspace generation to an immutable private revision","Reserve, upload, and validate an immutable .beckon revision as a draft","Set release-snapshotted contributor credits and edition metadata through the manifest","Create and revoke expiring draft preview links","Publish public or unlisted releases with an expected-latest concurrency guard","Read owned revision history","Publish a validated older revision as a rollback or restoration","Withdraw an owned release"],"forbidden":["Create or edit account creator and pen-name profiles","Change Supabase Auth identity or Puzzlelike product memberships","Assign itself as an author or prove a credited person's identity","Modify an immutable finalized revision in place","Overwrite browser edits or a newer workspace generation with a stale candidate","Publish into a publication owned by another account","Read or modify another account's private drafts, releases, keys, or profiles"],"manifestMetadata":{"contributors":["author","editor","translator","illustrator","narrator","publisher"],"publication":["title","description","language","direction","subjects","audience","identifiers","publisher","publishedDate"],"rights":["basis","territories","sourceUrl","license","copyrightNotice"],"structure":["readingOrder","resources","capabilities","styleProfile","cover"]},"workspaceModel":{"purpose":"Mutable, temporary, private iteration using the production Beckon validator and reader before an immutable revision is allocated.","states":["active","promoted","discarded","expired"],"workflow":["create-workspace","reserve-generation-guarded-upload","upload-bytes-directly-to-r2","validate-and-replace-candidate","review-or-browser-edit","retrieve-and-reconcile-browser-changes","promote-once"],"preview":"One stable secret preview URL follows the newest valid candidate. Invalid candidates leave the previous valid preview intact.","browserEditing":"Authenticated owners may replace validated structured blocks beside the production reader. Every edit retains stable IDs, creates before/after history, and advances the workspace generation.","sourceOfRecord":"Agents must retrieve pending browser changes and incorporate them into publisher source before uploading another candidate.","concurrency":"Candidate reservations, browser edits, and promotion require expectedGeneration. Stale mutations fail rather than overwriting newer work.","promotion":"Promotion creates one immutable private revision and does not publish it.","limits":{"activePerAccount":10,"maximumLifetimeHours":720,"signedUploadMinutes":15,"packageBytes":104857600},"mcpTools":["beckon_create_workspace","beckon_list_workspaces","beckon_get_workspace","beckon_reserve_workspace_upload","beckon_validate_workspace_upload","beckon_promote_workspace","beckon_discard_workspace"]},"nativeContent":{"richTextMarks":["emphasis","strong","code"],"markContract":"Zero-based UTF-16 code-unit ranges; start < end; end may not exceed text length.","tables":{"captionRequired":true,"columns":"1-12 unique columns","rows":"1-500 unique rows","cells":"Exactly one rich-text cell per column","rowHeaders":"At most one row-header column"}},"trustedCapabilities":{"beckon:stat-card@1":"Expandable semantic fact card with readable fallback prose.","beckon:message-thread@1":{"purpose":"Chronological incoming and outgoing story messages rendered by the trusted reader.","data":["optional title","1-20 unique participants","1-500 unique messages","senderId","direction","rich text with optional marks","optional timestamp","outgoing-only delivery status"],"deliveryStatuses":["sent","delivered","read","failed"],"fallback":"One or more core paragraphs preserving senders, sequence, and narratively meaningful status information.","prohibited":["author CSS","HTML","JavaScript","remote content","custom bubble colors or geometry"]},"beckon:composition@1.0":{"styleProfile":"beckon:utilities@1.0","utilities":["w-full","p-2","p-3","p-4","p-6","px-2","px-3","px-4","py-2","py-3","py-4","gap-1","gap-2","gap-3","gap-4","gap-6","items-start","items-center","items-end","justify-start","justify-center","justify-between","justify-end","grid-cols-1","grid-cols-2","grid-cols-3","grid-cols-4","sm:grid-cols-2","sm:grid-cols-3","sm:grid-cols-4","text-left","text-center","text-right","text-xs","text-sm","text-base","text-lg","text-xl","text-2xl","font-serif","font-sans","font-mono","font-normal","font-medium","font-semibold","font-bold","italic","uppercase","tracking-wide","tracking-wider","bg-surface","bg-surface-alt","bg-accent","text-ink","text-muted","text-accent","text-positive","text-negative","border","border-t","border-b","border-accent","rounded-sm","rounded","rounded-lg","shadow-sm","shadow-md","divide-y","animate-blink","animate-pulse","animate-glow"],"primitives":["stack","row","grid","heading","text","divider","stat-change"],"themeTokens":["surface","surfaceAlt","ink","muted","accent","positive","negative"],"themeContrast":"ink, muted, accent, positive, and negative require at least 4.5:1 contrast against surface; ink also requires 4.5:1 against surfaceAlt","motion":{"utilities":["animate-blink","animate-pulse","animate-glow"],"behavior":"Fixed Beckon-owned opacity or text-shadow animations; automatically disabled by prefers-reduced-motion; timing and keyframes are not publisher-configurable."},"budgets":{"nodes":300,"depth":12,"childrenPerGroup":50,"utilitiesPerNode":32},"safeguards":["exact utility allowlist","no arbitrary values","no executable code","no imports","no hooks","no handlers","no raw HTML","no forms","no remote URLs","no browser APIs","no positioning or z-index","CSS containment","required semantic fallback"]}},"releaseModel":{"identity":"publicationId remains stable; revision identifies one immutable validated package","states":["draft","published","superseded","withdrawn"],"visibility":["private","unlisted","public","withdrawn"],"changeTypes":["initial","correction","expanded","translation","new-edition","rollback"],"terminology":"An unpublished immutable revision may retain the legacy state value draft, but it is a release candidate—not a mutable workspace.","preferredWorkflow":["iterate-in-workspace","promote-approved-generation","review-immutable-release-candidate","explicit-publish","supersede-previous-latest","optional-rollback-or-withdraw"],"legacyDirectWorkflow":["reserve-immutable-upload","upload-bytes","finalize-as-draft","create-preview","explicit-publish"],"immutability":"A finalized publicationId + revision can never be replaced. Any byte or metadata change requires a new revision.","latestPointer":"Publishing atomically moves the publication latest_revision pointer; the previous latest becomes superseded.","concurrency":"Publish requires expectedLatestRevision. A stale value fails instead of silently overwriting another agent's publish.","discovery":"GET /api/v1/publications/:id/releases returns every owned revision, state, change type, timestamps, checksum, and is_latest.","rollback":"Publish a previously validated revision with changeType rollback and the current expectedLatestRevision.","restoration":"A withdrawn validated revision may be published again; its package bytes remain unchanged."},"endpoints":[{"method":"MCP","path":"beckon_create_workspace","purpose":"Create a mutable private preview workspace"},{"method":"MCP","path":"beckon_get_workspace","purpose":"Read its generation, candidate, and structured browser changes without polling"},{"method":"MCP","path":"beckon_reserve_workspace_upload","purpose":"Reserve a generation-guarded signed candidate upload"},{"method":"MCP","path":"beckon_validate_workspace_upload","purpose":"Validate and atomically replace the preview candidate"},{"method":"MCP","path":"beckon_promote_workspace","purpose":"Create one immutable private revision from the approved candidate"},{"method":"POST","path":"/api/v1/uploads","purpose":"Reserve an upload"},{"method":"POST","path":"/api/v1/uploads/:uploadId/finalize","purpose":"Validate and finalize an immutable draft"},{"method":"POST","path":"/api/v1/publications/:id/releases/:revision/preview-links","purpose":"Create an expiring preview"},{"method":"DELETE","path":"/api/v1/publications/:id/releases/:revision/preview-links/:linkId","purpose":"Revoke a preview"},{"method":"POST","path":"/api/v1/publications/:id/releases/:revision/publish","purpose":"Publish, restore, or roll back"},{"method":"GET","path":"/api/v1/publications/:id/releases","purpose":"Read owned release history"},{"method":"POST","path":"/api/v1/publications/:id/releases/:revision/withdraw","purpose":"Withdraw a release"}],"limits":{"maximumPackageBytes":104857600,"uploadUrlMinutes":15,"reservationMinutes":60,"maximumPreviewHours":720},"capabilityContractSha256":"381302f500319d491d75c0ab22ca16f6500599f18bc0e0c7b109c52ef867c96f"}