Skip to content

Publishing Flow

Load load_secondpage_skill({ "topic": "core" }) first, or check the exact installed skill version. Use topic: "publishing" for complete upload/export examples. A stale installed version returns fresh instructions.

Create

Search with list_pages({ query }) before creating a duplicate; follow next_cursor with the same query until has_more is false. Use create_page for new work. Matching runs before publication or signed upload URLs. target_review_required needs review of the returned evidence; use read/export/update for a revision or create_separate only after the user confirms a distinct Page.

Choose exactly one content input:

  • html: one self-contained document, up to 512 KiB of UTF-8 bytes; becomes index.html.
  • upload_files: a complete file inventory when HTTP is available. PUT missing files, then complete with upload_session_id.
  • files: the complete base64-encoded bundle when HTTP is unavailable.

Never mix these modes. A manifest is optional for the default index.html route. For a custom entrypoint or several routes, supply a manifest with schema_version "1.0", entrypoint and route-to-file mappings. File sizes/hashes come from upload_files; manifest.files is optional and must match the edited bytes if supplied.

Revise safely

Read the current Page to obtain base_version_id. If file_bundle is null, use export_page with export_type:html and retain the exported version_id and manifest so the files, base, entrypoint and routes match. Repeat that manifest on upload initiation and completion. Custom routes require upload mode; hand off the upload if the client cannot PUT files. Every update_page call requires base_version_id and replaces the entire bundle. On version_conflict, read/export again, reconcile the new changes, and reapply the edit. Do not resend old files with a newer base without checking them.

Both opening and completing an update upload session require the same base. Keep the original requested metadata on completion, including title, source_meta and update_reason. A rename with unchanged files still updates the title. A fully identical request returns no_change without creating a version.

MCP agents cannot change existing Page sharing, including with OAuth. Omit visibility on updates or repeat the current value; humans change access in Sharing. New Pages default to organization. Return the Page URL and who can see it.

Upload and media

Upload only files marked upload_required, using the returned URL and required_headers. If a session expires, open a new one. After an intervening revision, reconcile and start a new update session. Include every referenced asset in the replacement bundle.

For direct media, call create_media_upload, PUT the bytes, then complete_media_upload and use asset_url. Explicit media_asset_ids are supported on inline/html publication; signed upload modes include assets in their file inventory.

Feedback and failures

Read comments with page_id and queued_only:true. Apply the requested change to a complete fresh bundle, then reply with add_comment and parent_comment_id. Inspect warnings before claiming the Page is finished. Check isError and the stable error code; use recovery or next_action and respect retry_after_seconds. Queued work is pending, not completion.

See Page Exports, Live Data, and Page Capacity.