Edit websites through a client

A client can create and edit a private website draft. Publication, withdrawal and restoration require the delegated person's approval.

For: developers connecting an HTTP or MCP client. What you need: website grants, the delegated person's website permissions and current access to every selected source.

Start with Connect your client. These tools use the same website rules as the editor; they need no AI provider.

Customer account boundary

Published websites expose a separate customer Account surface when the Customers module is available. No website snapshot toggle enables or disables it.

Website tools do not sign in customers, reveal their sessions or grant access to purchases. Use the scoped customer-account staff tools for permitted account administration.

Changing a website's address or withdrawing publication invalidates its account sessions. Ordinary content publication does not require every customer to sign in again.

Choose grants

Source discovery also requires websites.manage. Ordinary reads require websites.view; creating or saving requires websites.manage.

Publishing, withdrawing and publishing from history require websites.publish. Restoring a private draft requires websites.manage plus the sensitive approval flow.

Every call checks the person's active account and current source access. Guests and customer-workspace actors cannot use these installation website tools.

Discover and read

HTTP paths below follow /api/v1/. Use bearer authentication from Transport and authentication.

Qualified tool keys use dots, such as websites.get. MCP names use underscores, such as websites_get.

List search accepts up to 100 characters. Website lists sort by updated_at or name; source lists sort by name.

For older history, pass the last returned version number as before. Do not assume version numbers are consecutive.

hosting.mode is hostname, address, local or unconfigured. cname_target comes from the configured installation hostname; address_records contains only explicitly configured public IP addresses.

The read result makes no DNS or HTTPS verification claim. Root-domain A or AAAA addresses remain the operator's responsibility. Read domain setup.

Use the installed tool declarations for exact schemas. A source choice does not grant permission to upload, change or publish that source.

If snapshot_json is null and recovery is required, retain the client draft. Restore source access and read again before saving.

Do not reconstruct editable content from rendered public HTML. That could replace content the person cannot currently read.

Read website insights

Use analytics_read or GET /api/v1/analytics with site_id. Add site_page or locale to match the editor's Insights selection.

These reads require analytics:read, View analytics and permission to view the website. A website read grant alone does not grant analytics access.

The report counts eligible requests for published pages. Previewing or saving a draft creates no page views. Website traffic never increases widget counts.

See the shared analytics reporting rules for dates, filters, privacy, exact records and currency handling.

Manage page codes

A website owns the QR codes made for its pages. These tools use the same rules as QR codes in the editor's Pages panel. Read Print a QR code for a page for the owner's view.

1. Call websites_codes. Pick a page from pages.
2. Call websites_code_save with an idempotency_key and a payload with target.page_id. Add target.campaign_id or target.locale when needed.
3. Call websites_code_print with format pdf, svg or png. Open download_url within 5 minutes. It works once.

payload accepts only name, channel, print_quantity, style, version and target. Another field answers 422. Without name, a new code takes the page title. A new code uses the print channel. To change a code, send its current version. An edit without name keeps the code's name. Send the same key and payload again to recover the same code after a lost answer.

Each code has target.page.state:

Follow Approve sensitive steps to close a code.

Pepper refuses a page that is not published, a language the website does not offer and a campaign of another website. Each refusal names the field. Closing keeps the printed code working: a scan then opens the home page, without the code's campaign.

A widget's own codes stay with the widget tools. Their target also accepts a site_page destination. See Forms and widgets.

Create and save a private draft

websites_create requires template, name, slug, locale and an idempotency_key. Use an installed language and a lowercase path slug.

The name allows 160 characters; the slug allows 80. The created template remains unpublished. Select or remove its contact widget before publication.

websites_save requires id, the current version, complete snapshot_json and an idempotency_key. It saves the validated snapshot as one operation.

HTTP uses POST websites for creation and PUT websites/{id}/draft for saving. Put write keys in the Idempotency-Key header.

Omit the path id and idempotency_key from HTTP JSON bodies. MCP sends both in its arguments.

The snapshot includes pages, page parents, navigation, languages, global header and footer, design and source references. Read the current snapshot before changing it.

Design uses these snapshot fields:

props.treatment is available on every website block, alongside its declared properties. Preserve omitted optional fields when making unrelated edits.

Rendering leaves the saved snapshot and its hash unchanged. A deliberate design save creates a new version through the ordinary save action.

The server derives colours for pages, previews and widgets placed on the website. Clients do not send derived palettes, CSS or font URLs.

Search and sharing uses these optional fields:

The translated description retains its 320-character limit. A blank value resolves from that language's first introduction or text section.

Preserve omitted fields when making unrelated edits. Reading or previewing a snapshot does not add defaults or change its hash.

Page and website visibility combine with automatic exclusions for functional pages. A catalogue page can include an inline cart and remain indexable.

noindex controls search inclusion, not access. A published page remains readable by anyone with its address.

The server derives canonical addresses, language alternatives, structured data, icons and share cards. Clients cannot supply executable markup or override these outputs.

An image selection uses current Files access and the exact retained version. Generated public image addresses are checked against the current publication and source access on every request.

Generated images require cache revalidation. A matching ETag does not bypass withdrawal or source revocation. Private previews return image data URLs, without publishing draft assets.

Keep name, slug, host, locales and default_locale inside the complete snapshot_json. These settings join the same atomic draft save.

The editor exposes these fields and language choices under Settings. Changing them saves no DNS record and does not publish the website.

Blocks site_shop and site_cart reference a published shop_cart widget. site_product references a published buy_button widget.

Each uses widget_id; the ordinary source, current publication and exact allowed-origin checks remain in force. Draft previews create no carts, orders or payments.

Keep stable page and block identities when editing. Give each inserted block a unique stable ID instead of reusing the starter block's ID.

A snapshot allows 50 pages, 3 page levels and 200 sections per page. After decoding the outer request, snapshot_json allows 1,048,576 bytes.

Only website save and preview accept an encoded HTTP or MCP request body up to 8 MiB. This allows JSON escaping around the snapshot string. Other website tools retain the default 256 KiB request limit.

A larger envelope does not increase the decoded snapshot limit. See transport limits.

Image references pair file_id with version_id. Preserve the pair when retaining an image. A file's replacement upload does not change this reference.

A stale version refuses the save. Keep local content and reconcile against a fresh read. Never silently overwrite the newer draft.

If a response is lost, repeat the identical request with the same key. Do not create a new key until making a different request.

Preview unsaved content

Call websites_preview or POST websites/{id}/preview with id, snapshot_json, page_id, locale and a fresh UUID channel.

The result contains html, source issues and a derived search projection. Display the HTML in a frame with sandbox="allow-scripts". Never grant same-origin authority.

search contains the title, description, URL, effective noindex, automatic_noindex, language alternatives, both icon data URLs, the share image and field warnings.

Use automatic_noindex to avoid offering a page switch that cannot change the result. Preview HTML itself always excludes indexing.

Image previews include dimensions and alt text. Keep their data URLs private and use the returned values; do not guess a public asset address.

The optional mode is edit by default. Use browse for read-only navigation through the supplied snapshot. External links stay inactive.

Browse navigation and language links in an edit preview send this message to the parent:

{"type":"pepper-website-preview","action":"navigate","channel":"<current-channel>","pageId":"<snapshot-page-id>","locale":"es"}

Check the frame's source window, opaque null origin and current channel. Accept only page IDs and locales in the displayed snapshot.

Request the destination with the same snapshot and a fresh channel. Discard messages from a replaced frame.

Preview neither saves nor publishes. Widgets remain inactive placeholders and create no visitor actions.

Request an approved lifecycle change

Discover each declaration through HTTP GET /api/v1/tools or MCP tools/list. Follow Approve sensitive steps for approval and execution.

Preparation includes the current version. Restoration and rollback also need the selected version_id.

websites_review accepts an operation and, for historical content, version_id. It provides an inspection result, not permission to execute.

The approval shows the address, content and connected sources. Changes to the website or those sources invalidate the reviewed request.

After a conflict, read the latest state and prepare a new request for approval. Do not reuse an approval for changed content.

Restoration and rollback retain the website's current address and all history. Rollback rechecks current sources and catalogue values; it does not restore old prices.

Publication compares page paths by stable page identity. Changed paths, including descendant moves, receive redirects to the current page for 12 months.

Draft saves create no redirects. Removing the page or language, or reusing an old path, ends its redirect. Website slug and host changes create no old-address redirect.

Recover unavailable sources

An image, catalogue item or widget keeps its own access and publication rules. A successful website read grants no extra source permission.

Use the source's ordinary tools to correct it when authorized. Otherwise, ask someone with access to restore it.

A retained website version cannot reopen a deleted source. An authorized publisher can still withdraw a website whose editable draft is withheld.

See Build and publish a website for consent, language and history rules. See domain setup before requesting custom-host publication.