---
updatedAt: 2026-11-17T14:46:05.000Z
agentTools:
  projectIndex: https://developer.duda.co/llms.txt
---

# MCP Server Reference

## Available Tools List

Below is the list of tools / features that Duda's MCP server exposes. Availability of these varies based on your plan type, as specified in the table below.

## Tools

| Category        | Tool                             | Plan        | Access              | What it does                                                                                                                                                                                                                                                                                                                                                    |
| --------------- | -------------------------------- | ----------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accounts        | `create_account`                 | Team        | Write (destructive) | Create account                                                                                                                                                                                                                                                                                                                                                  |
|                 | `get_account_details`            | Team        | Read-only           | Get account details                                                                                                                                                                                                                                                                                                                                             |
|                 | `update_account`                 | Team        | Write (destructive) | Update account                                                                                                                                                                                                                                                                                                                                                  |
|                 | `delete_account`                 | Team        | Write (destructive) | Delete account                                                                                                                                                                                                                                                                                                                                                  |
|                 | `list_site_permissions`          | Team        | Read-only           | List site permissions                                                                                                                                                                                                                                                                                                                                           |
|                 | `grant_site_access`              | Team        | Write (destructive) | Grant site access                                                                                                                                                                                                                                                                                                                                               |
|                 | `update_site_permissions`        | Team        | Write (destructive) | Update site permissions                                                                                                                                                                                                                                                                                                                                         |
|                 | `revoke_site_access`             | Team        | Write (destructive) | Revoke site access                                                                                                                                                                                                                                                                                                                                              |
|                 | `generate_sso_link`              | Custom Plan | Write (destructive) | Generate SSO link                                                                                                                                                                                                                                                                                                                                               |
|                 | `generate_reset_password_link`   | Custom Plan | Write (destructive) | Generate password reset link                                                                                                                                                                                                                                                                                                                                    |
|                 | `create_welcome_link`            | Team        | Write (destructive) | Create welcome link                                                                                                                                                                                                                                                                                                                                             |
|                 | `get_client_permission_for_site` | Team        | Read-only           | Get client site permissions                                                                                                                                                                                                                                                                                                                                     |
|                 | `list_client_sites`              | Team        | Read-only           | List client sites                                                                                                                                                                                                                                                                                                                                               |
| Blog            | `list_blog_posts`                | Basic       | Read-only           | List blog posts                                                                                                                                                                                                                                                                                                                                                 |
|                 | `get_blog_post`                  | Basic       | Read-only           | Get blog post                                                                                                                                                                                                                                                                                                                                                   |
|                 | `create_blog_post`               | Basic       | Write (destructive) | Create blog post                                                                                                                                                                                                                                                                                                                                                |
|                 | `update_blog_post`               | Basic       | Write (destructive) | Update blog post                                                                                                                                                                                                                                                                                                                                                |
|                 | `delete_blog_post`               | Basic       | Write (destructive) | Delete blog post                                                                                                                                                                                                                                                                                                                                                |
|                 | `publish_blog_post`              | Basic       | Write (destructive) | Publish blog post                                                                                                                                                                                                                                                                                                                                               |
|                 | `unpublish_blog_post`            | Basic       | Write (destructive) | Unpublish blog post                                                                                                                                                                                                                                                                                                                                             |
|                 | `create_blog`                    | Basic       | Write (destructive) | Create blog                                                                                                                                                                                                                                                                                                                                                     |
|                 | `update_blog`                    | Basic       | Write (destructive) | Update blog settings                                                                                                                                                                                                                                                                                                                                            |
|                 | `import_blog_posts_from_rss`     | Basic       | Write (destructive) | Import blog posts from RSS                                                                                                                                                                                                                                                                                                                                      |
|                 | `read_blog`                      | Basic       | Read-only           | Get blog settings                                                                                                                                                                                                                                                                                                                                               |
| Content Library | `get_content_library`            | Basic       | Read-only           | Get content library                                                                                                                                                                                                                                                                                                                                             |
|                 | `update_content_library`         | Basic       | Write (destructive) | Update content library                                                                                                                                                                                                                                                                                                                                          |
|                 | `publish_content_library`        | Basic       | Write (destructive) | Publish content library data                                                                                                                                                                                                                                                                                                                                    |
| Ecommerce       | `get_store_details`              | Basic       | Read-only           | Get store details                                                                                                                                                                                                                                                                                                                                               |
|                 | `create_store`                   | Basic       | Write (destructive) | Create store                                                                                                                                                                                                                                                                                                                                                    |
|                 | `list_store_products`            | Basic       | Read-only           | List store products                                                                                                                                                                                                                                                                                                                                             |
|                 | `get_store_product`              | Basic       | Read-only           | Get store product                                                                                                                                                                                                                                                                                                                                               |
|                 | `create_store_products`          | Basic       | Write (destructive) | Create store products                                                                                                                                                                                                                                                                                                                                           |
|                 | `update_store_product`           | Basic       | Write (destructive) | Update store product                                                                                                                                                                                                                                                                                                                                            |
|                 | `bulk_update_store_products`     | Basic       | Write (destructive) | Bulk update store products                                                                                                                                                                                                                                                                                                                                      |
|                 | `delete_store_product`           | Basic       | Write (destructive) | Delete store product                                                                                                                                                                                                                                                                                                                                            |
|                 | `get_product_variation`          | Basic       | Read-only           | Get product variation                                                                                                                                                                                                                                                                                                                                           |
|                 | `update_product_variation`       | Basic       | Write (destructive) | Update product variation                                                                                                                                                                                                                                                                                                                                        |
|                 | `create_product_customizations`  | Basic       | Write               | Create product customizations                                                                                                                                                                                                                                                                                                                                   |
|                 | `list_product_customizations`    | Basic       | Read-only           | List product customizations                                                                                                                                                                                                                                                                                                                                     |
|                 | `update_product_customizations`  | Basic       | Write (destructive) | Update product customizations                                                                                                                                                                                                                                                                                                                                   |
|                 | `delete_product_customizations`  | Basic       | Write (destructive) | Delete product customizations                                                                                                                                                                                                                                                                                                                                   |
|                 | `list_store_orders`              | Basic       | Read-only           | List store orders                                                                                                                                                                                                                                                                                                                                               |
|                 | `get_store_order`                | Basic       | Read-only           | Get store order                                                                                                                                                                                                                                                                                                                                                 |
|                 | `update_store_order`             | Basic       | Write (destructive) | Update store order                                                                                                                                                                                                                                                                                                                                              |
| Reporting       | `get_site_stats`                 | Basic       | Read-only           | Get site statistics                                                                                                                                                                                                                                                                                                                                             |
|                 | `get_site_activities`            | Basic       | Read-only           | Get site activity log                                                                                                                                                                                                                                                                                                                                           |
|                 | `list_form_submissions`          | Basic       | Read-only           | List form submissions                                                                                                                                                                                                                                                                                                                                           |
|                 | `published_sites_by_date`        | Basic       | Read-only           | Find recently published sites                                                                                                                                                                                                                                                                                                                                   |
|                 | `created_sites_by_date`          | Basic       | Read-only           | Find recently created sites                                                                                                                                                                                                                                                                                                                                     |
| Sites           | `list_sites`                     | Basic       | Read-only           | List sites                                                                                                                                                                                                                                                                                                                                                      |
|                 | `get_site_details`               | Basic       | Read-only           | Get site details                                                                                                                                                                                                                                                                                                                                                |
|                 | `publish_site`                   | Custom Plan | Write (destructive) | Publish site                                                                                                                                                                                                                                                                                                                                                    |
|                 | `unpublish_site`                 | Custom Plan | Write (destructive) | Unpublish site                                                                                                                                                                                                                                                                                                                                                  |
|                 | `create_or_generate_site`        | Basic       | Write (destructive) | Create site                                                                                                                                                                                                                                                                                                                                                     |
| Templates       | `list_templates`                 | Basic       | Read-only           | List site templates                                                                                                                                                                                                                                                                                                                                             |
| Pages           | `list_pages`                     | Basic       | Read-only           | List pages                                                                                                                                                                                                                                                                                                                                                      |
|                 | `update_page_settings`           | Basic       | Write (destructive) | Update page settings                                                                                                                                                                                                                                                                                                                                            |
|                 | `create_page`                    | Basic       | Write (destructive) | Create page                                                                                                                                                                                                                                                                                                                                                     |
|                 | `duplicate_page`                 | Basic       | Write               | Duplicate page                                                                                                                                                                                                                                                                                                                                                  |
|                 | `delete_page`                    | Basic       | Write (destructive) | Delete page                                                                                                                                                                                                                                                                                                                                                     |
| Popups          | `list_popups`                    | Basic       | Read-only           | List popups                                                                                                                                                                                                                                                                                                                                                     |
|                 | `create_popup`                   | Basic       | Write (destructive) | Create popup                                                                                                                                                                                                                                                                                                                                                    |
|                 | `update_popup_settings`          | Basic       | Write (destructive) | Update popup settings                                                                                                                                                                                                                                                                                                                                           |
|                 | `delete_popup`                   | Basic       | Write (destructive) | Delete popup                                                                                                                                                                                                                                                                                                                                                    |
| Collections     | `get_collections`                | Basic       | Read-only           | Get collections                                                                                                                                                                                                                                                                                                                                                 |
|                 | `create_collection`              | Basic       | Write (destructive) | Create collection                                                                                                                                                                                                                                                                                                                                               |
|                 | `create_collection_rows`         | Basic       | Write (destructive) | Add collection rows                                                                                                                                                                                                                                                                                                                                             |
|                 | `update_collection_rows`         | Basic       | Write (destructive) | Update collection rows                                                                                                                                                                                                                                                                                                                                          |
|                 | `patch_collection_rows`          | Basic       | Write               | Patch collection rows                                                                                                                                                                                                                                                                                                                                           |
|                 | `delete_collection_rows`         | Basic       | Write (destructive) | Delete collection rows                                                                                                                                                                                                                                                                                                                                          |
|                 | `create_collection_fields`       | Basic       | Write (destructive) | Add collection fields                                                                                                                                                                                                                                                                                                                                           |
|                 | `update_collection_field`        | Basic       | Write (destructive) | Update collection field                                                                                                                                                                                                                                                                                                                                         |
|                 | `delete_collection_field`        | Basic       | Write (destructive) | Delete collection field                                                                                                                                                                                                                                                                                                                                         |
|                 | `delete_collection`              | Basic       | Write (destructive) | Delete collection                                                                                                                                                                                                                                                                                                                                               |
|                 | `publish_collection`             | Basic       | Write               | Publish collection                                                                                                                                                                                                                                                                                                                                              |
|                 | `update_collection`              | Basic       | Write               | Update collection                                                                                                                                                                                                                                                                                                                                               |
|                 | `revalidate_collection`          | Basic       | Write               | Revalidate collection                                                                                                                                                                                                                                                                                                                                           |
| Theme           | `get_site_theme`                 | Basic       | Read-only           | Get site theme                                                                                                                                                                                                                                                                                                                                                  |
|                 | `update_site_theme`              | Basic       | Write (destructive) | Update site theme                                                                                                                                                                                                                                                                                                                                               |
| URL Rules       | `list_url_rules`                 | Team        | Read-only           | List URL rules                                                                                                                                                                                                                                                                                                                                                  |
|                 | `create_url_rule`                | Team        | Write (destructive) | Create URL rule                                                                                                                                                                                                                                                                                                                                                 |
|                 | `update_url_rule`                | Team        | Write (destructive) | Update URL rule                                                                                                                                                                                                                                                                                                                                                 |
|                 | `delete_url_rule`                | Team        | Write (destructive) | Delete URL rule                                                                                                                                                                                                                                                                                                                                                 |
| Booking         | `create_booking`                 | Basic       | Write (destructive) | Create booking organization                                                                                                                                                                                                                                                                                                                                     |
|                 | `get_booking`                    | Basic       | Read-only           | Get booking organization                                                                                                                                                                                                                                                                                                                                        |
|                 | `update_booking_status`          | Basic       | Write (destructive) | Update booking status                                                                                                                                                                                                                                                                                                                                           |
|                 | `get_booking_appt_types`         | Basic       | Read-only           | Get appointment types                                                                                                                                                                                                                                                                                                                                           |
|                 | `create_booking_appt_type`       | Basic       | Write (destructive) | Create appointment type                                                                                                                                                                                                                                                                                                                                         |
|                 | `update_booking_appt_type`       | Basic       | Write (destructive) | Update appointment type                                                                                                                                                                                                                                                                                                                                         |
|                 | `delete_booking_appt_type`       | Basic       | Write (destructive) | Delete appointment type                                                                                                                                                                                                                                                                                                                                         |
|                 | `list_booking_appts`             | Basic       | Read-only           | List appointments                                                                                                                                                                                                                                                                                                                                               |
|                 | `get_booking_staff`              | Basic       | Read-only           | Get booking staff                                                                                                                                                                                                                                                                                                                                               |
|                 | `create_booking_staff`           | Basic       | Write (destructive) | Create staff member                                                                                                                                                                                                                                                                                                                                             |
|                 | `update_booking_staff`           | Basic       | Write (destructive) | Update staff member                                                                                                                                                                                                                                                                                                                                             |
|                 | `delete_booking_staff`           | Basic       | Write (destructive) | Delete staff member                                                                                                                                                                                                                                                                                                                                             |
|                 | `get_booking_staff_avail`        | Basic       | Read-only           | Get staff availability                                                                                                                                                                                                                                                                                                                                          |
|                 | `update_booking_staff_avail`     | Basic       | Write (destructive) | Update staff availability                                                                                                                                                                                                                                                                                                                                       |
| Marketing       | `marketing_list_custom_fields`   | Custom Plan | Read-only           | Lists all marketing custom field definitions for a site.                                                                                                                                                                                                                                                                                                        |
|                 | `marketing_create_custom_field`  | Custom Plan | Write (destructive) | Creates a new marketing custom field definition.                                                                                                                                                                                                                                                                                                                |
|                 | `marketing_update_custom_field`  | Custom Plan | Write (destructive) | Updates a marketing custom field definition. field\_key and field\_type cannot be changed after creation.                                                                                                                                                                                                                                                       |
|                 | `marketing_delete_custom_field`  | Custom Plan | Write (destructive) | Deletes a marketing custom field definition.                                                                                                                                                                                                                                                                                                                    |
|                 | `marketing_find_contacts`        | Custom Plan | Read-only           | Find marketing contacts with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call) so you pick correct paths instead of guessing.                                                                                                                  |
|                 | `marketing_import_contacts`      | Custom Plan | Write (destructive) | Creates contacts in bulk (1–100 per call, continue-on-error).                                                                                                                                                                                                                                                                                                   |
|                 | `marketing_update_contacts`      | Custom Plan | Write (destructive) | Updates contacts in bulk (1–100 per call, continue-on-error, PATCH semantics).                                                                                                                                                                                                                                                                                  |
|                 | `marketing_delete_contacts`      | Custom Plan | Write (destructive) | Permanently deletes contacts by id (1–100).                                                                                                                                                                                                                                                                                                                     |
|                 | `marketing_set_subscription`     | Custom Plan | Write (destructive) | Sets per-channel marketing subscription state for contacts (1–100).                                                                                                                                                                                                                                                                                             |
|                 | `marketing_find_segments`        | Custom Plan | Read-only           | Find marketing segments with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call) so you pick correct paths instead of guessing.                                                                                                                  |
|                 | `marketing_create_segment`       | Custom Plan | Write (destructive) | Creates a marketing segment.                                                                                                                                                                                                                                                                                                                                    |
|                 | `marketing_update_segment`       | Custom Plan | Write (destructive) | Updates a marketing segment. segment\_type cannot be changed after creation.                                                                                                                                                                                                                                                                                    |
|                 | `marketing_delete_segment`       | Custom Plan | Write (destructive) | Deletes a marketing segment.                                                                                                                                                                                                                                                                                                                                    |
|                 | `marketing_set_segment_members`  | Custom Plan | Write (destructive) | Adds contacts to, or removes them from, a STATIC segment's membership (1-100 contacts). member=true adds, member=false removes; removing a contact from a segment does not delete the contact.                                                                                                                                                                  |
|                 | `marketing_find_email_tmpls`     | Custom Plan | Read-only           | Find email templates with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog PLUS email\_json\_spec (block-graph shape, the supported block types, validation rules) and merge\_tokens, with NO API call, making it your reference for composing email\_json. |
|                 | `marketing_create_email_tmpl`    | Custom Plan | Write (destructive) | Creates a new email template.                                                                                                                                                                                                                                                                                                                                   |
|                 | `marketing_update_email_tmpl`    | Custom Plan | Write (destructive) | Updates an existing email template.                                                                                                                                                                                                                                                                                                                             |
|                 | `marketing_delete_email_tmpl`    | Custom Plan | Write (destructive) | Deletes an email template.                                                                                                                                                                                                                                                                                                                                      |
|                 | `marketing_email_tmpl_library`   | Custom Plan | Read-only           | Returns the built-in email template library — the designed templates the editor gallery offers — each already seeded with this site's theme and carrying guidance on when its layout fits.                                                                                                                                                                      |
|                 | `marketing_email_recipe`         | Custom Plan | Read-only           | Email composition recipe                                                                                                                                                                                                                                                                                                                                        |
|                 | `marketing_find_campaigns`       | Custom Plan | Read-only           | Find marketing campaigns with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call) so you pick correct paths instead of guessing.                                                                                                                 |
|                 | `marketing_create_campaign`      | Custom Plan | Write (destructive) | Creates a marketing campaign in draft status.                                                                                                                                                                                                                                                                                                                   |
|                 | `marketing_update_campaign`      | Custom Plan | Write (destructive) | Updates a campaign in draft status.                                                                                                                                                                                                                                                                                                                             |
|                 | `marketing_delete_campaign`      | Custom Plan | Write (destructive) | Deletes a campaign.                                                                                                                                                                                                                                                                                                                                             |
|                 | `marketing_send_campaign`        | Custom Plan | Write (destructive) | DESTRUCTIVE: Sends a draft campaign (using its already-configured recipient\_type / segment\_id / recipient\_ids) to real subscribers.                                                                                                                                                                                                                          |
|                 | `marketing_find_automations`     | Custom Plan | Read-only           | Find marketing automations with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call) so you pick correct paths instead of guessing.                                                                                                               |
|                 | `marketing_auto_enrollments`     | Custom Plan | Read-only           | Who an automation has enrolled and what happened to each of them.                                                                                                                                                                                                                                                                                               |
|                 | `marketing_create_automation`    | Custom Plan | Write (destructive) | Creates an automation in inactive status.                                                                                                                                                                                                                                                                                                                       |
|                 | `marketing_update_automation`    | Custom Plan | Write (destructive) | Updates an automation envelope (PATCH semantics) — name, trigger, recipients, goal, schedule.                                                                                                                                                                                                                                                                   |
|                 | `marketing_delete_automation`    | Custom Plan | Write (destructive) | Deletes an automation.                                                                                                                                                                                                                                                                                                                                          |
|                 | `marketing_set_automation_state` | Custom Plan | Write (destructive) | Activates or pauses an automation. status="active" starts real sends for matching events (route: /activate); "paused" stops new enrollment and halts in-flight progression (route: /deactivate).                                                                                                                                                                |
|                 | `marketing_set_auto_archived`    | Custom Plan | Write (destructive) | Archives an automation or restores it. archived=true takes it off the live list without changing its status or stopping anything already enrolled (route: /archive); archived=false puts it back (route: /restore).                                                                                                                                             |
|                 | `marketing_automation_library`   | Custom Plan | Read-only           | Returns the curated library of starter automations: welcome-series, order-confirmation, win-back, birthday-greeting and renewal-reminder.                                                                                                                                                                                                                       |
|                 | `marketing_auto_add_step`        | Custom Plan | Write (destructive) | Adds a single step to an EXISTING automation — fully supported; use it to append/insert a step (e.g. a follow-up send\_email, a wait, or a condition) without recreating the automation, and never say modifying an existing automation is unsupported.                                                                                                         |
|                 | `marketing_auto_update_step`     | Custom Plan | Write (destructive) | Edits a step IN AN EXISTING AUTOMATION in place — fully supported; NEVER tell the user that editing an automation's email content/steps is unsupported or that they must use the dashboard builder.                                                                                                                                                             |
|                 | `marketing_auto_delete_step`     | Custom Plan | Write (destructive) | Deletes a single step from an automation.                                                                                                                                                                                                                                                                                                                       |
|                 | `marketing_auto_reorder_steps`   | Custom Plan | Write (destructive) | Reorders an automation's steps. step\_ids must be the EXACT full set of the automation's current step UUIDs (every step exactly once) in the desired order — the server rejects a partial, duplicate, or foreign id set.                                                                                                                                        |
|                 | `marketing_list_variables`       | Custom Plan | Read-only           | Lists the merge variables usable in email/SMS subject and body for this site.                                                                                                                                                                                                                                                                                   |
|                 | `marketing_link_targets`         | Custom Plan | Read-only           | Linkable pages, posts and products                                                                                                                                                                                                                                                                                                                              |
|                 | `marketing_list_labels`          | Custom Plan | Read-only           | Lists the site's labels.                                                                                                                                                                                                                                                                                                                                        |
|                 | `marketing_create_label`         | Custom Plan | Write (destructive) | Creates a label on its own, tagging nobody.                                                                                                                                                                                                                                                                                                                     |
|                 | `marketing_get_limits`           | Custom Plan | Read-only           | Returns what the site's plan allows in marketing and how much of it the site has used.                                                                                                                                                                                                                                                                          |
|                 | `marketing_check_suggestions`    | Custom Plan | Read-only           | Checks a draft of the marketing Home suggestions (3 emails or none, 1 SMS, 1 automation) with the same rules the Home card applies, and returns \{ clean, email\_problems, sms\_problems, automation\_problems }; each problem names the item id and the field.                                                                                                 |
| Vibe            | `vibe_list_files`                | Basic       | Read-only           | List Vibe project files                                                                                                                                                                                                                                                                                                                                         |
|                 | `vibe_read_files`                | Basic       | Read-only           | Read Vibe project files                                                                                                                                                                                                                                                                                                                                         |
|                 | `vibe_get_tables`                | Basic       | Read-only           | Get Vibe tables                                                                                                                                                                                                                                                                                                                                                 |
|                 | `vibe_query_rows`                | Basic       | Read-only           | Read Vibe table rows                                                                                                                                                                                                                                                                                                                                            |
|                 | `vibe_edit_tables`               | Basic       | Write               | Edit Vibe tables                                                                                                                                                                                                                                                                                                                                                |
|                 | `vibe_edit_rows`                 | Basic       | Write (destructive) | Edit Vibe table rows                                                                                                                                                                                                                                                                                                                                            |
| Conversations   | `conversation_find`              | Basic       | Read-only           | Find conversations                                                                                                                                                                                                                                                                                                                                              |
|                 | `conversation_get_messages`      | Basic       | Read-only           | Get conversation messages                                                                                                                                                                                                                                                                                                                                       |
|                 | `conversation_send_message`      | Basic       | Write               | Send a message                                                                                                                                                                                                                                                                                                                                                  |
|                 | `conversation_wait`              | Basic       | Read-only           | Wait for a conversation turn                                                                                                                                                                                                                                                                                                                                    |
|                 | `conversation_cancel`            | Basic       | Write (destructive) | Cancel a conversation                                                                                                                                                                                                                                                                                                                                           |
| Elements        | `get_element_schema`             | Basic       | Read-only           | Element schema                                                                                                                                                                                                                                                                                                                                                  |
|                 | `get_binding_options`            | Basic       | Read-only           | Binding options                                                                                                                                                                                                                                                                                                                                                 |
|                 | `search_site_text`               | Basic       | Read-only           | Search site text                                                                                                                                                                                                                                                                                                                                                |
|                 | `get_page_elements`              | Basic       | Read-only           | Page elements                                                                                                                                                                                                                                                                                                                                                   |
|                 | `insert_elements`                | Basic       | Write               | Insert elements                                                                                                                                                                                                                                                                                                                                                 |
|                 | `delete_element`                 | Basic       | Write (destructive) | Delete element                                                                                                                                                                                                                                                                                                                                                  |
|                 | `move_element`                   | Basic       | Write (destructive) | Move element                                                                                                                                                                                                                                                                                                                                                    |
|                 | `duplicate_element`              | Basic       | Write               | Duplicate element                                                                                                                                                                                                                                                                                                                                               |
|                 | `update_elements`                | Basic       | Write (destructive) | Update elements                                                                                                                                                                                                                                                                                                                                                 |
| AEO             | `get_aeo_report`                 | Basic       | Read-only           | Get AI Visibility report                                                                                                                                                                                                                                                                                                                                        |
|                 | `create_aeo`                     | Basic       | Write               | Start AI Visibility tracking or a one-time report                                                                                                                                                                                                                                                                                                               |
|                 | `manage_aeo_project`             | Basic       | Write (destructive) | Pause, resume or refresh AI Visibility tracking                                                                                                                                                                                                                                                                                                                 |
|                 | `get_aeo_prompts`                | Basic       | Read-only           | Read AI Visibility prompts                                                                                                                                                                                                                                                                                                                                      |
|                 | `update_aeo_prompts`             | Basic       | Write               | Add AI Visibility prompts                                                                                                                                                                                                                                                                                                                                       |
|                 | `archive_aeo_prompts`            | Basic       | Write (destructive) | Archive AI Visibility prompts                                                                                                                                                                                                                                                                                                                                   |
|                 | `restore_aeo_prompts`            | Basic       | Write               | Restore AI Visibility prompts                                                                                                                                                                                                                                                                                                                                   |
|                 | `get_aeo_competitors`            | Basic       | Read-only           | Read AI Visibility competitors                                                                                                                                                                                                                                                                                                                                  |
|                 | `update_aeo_competitors`         | Basic       | Write               | Add AI Visibility competitors                                                                                                                                                                                                                                                                                                                                   |
|                 | `edit_aeo_competitors`           | Basic       | Write (destructive) | Edit AI Visibility competitors                                                                                                                                                                                                                                                                                                                                  |
|                 | `remove_aeo_competitors`         | Basic       | Write (destructive) | Remove AI Visibility competitors                                                                                                                                                                                                                                                                                                                                |
|                 | `get_aeo_settings`               | Basic       | Read-only           | Read AI Visibility settings                                                                                                                                                                                                                                                                                                                                     |
|                 | `add_aeo_settings`               | Basic       | Write               | Add AI Visibility settings                                                                                                                                                                                                                                                                                                                                      |
|                 | `remove_aeo_settings`            | Basic       | Write (destructive) | Remove AI Visibility settings                                                                                                                                                                                                                                                                                                                                   |

## Tool details

### Accounts

<Accordion title="create_account" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Creates a new Duda customer account that can be granted access to websites. This creates a standard customer account (not a staff account). After creation, you'll need to provide this user with a welcome link (using create_welcome_link) or grant them specific site access permissions (using grant_site_access).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username for the account (must be provided by user). This acts as the account identifier and login username. Must be unique across all Duda accounts. Can be an email address, but doesn't need to be. |
| `first_name` | string | no | User's first name. Leave undefined if not provided. |
| `last_name` | string | no | User's last name. Leave undefined if not provided. |
| `lang` | string | no | Language code for the account interface (e.g., 'en', 'es', 'fr'). Leave undefined if not specified. |
| `email` | string | no | Email address for account notifications and password reset. Leave undefined if not provided. |
| `company_name` | string | no | Company name. Leave undefined if not provided. |
</Accordion>

<Accordion title="get_account_details" icon="fa-eye">
**Plan:** Team · **Access:** Read-only

Retrieves comprehensive information about a specific Duda customer account. Returns account profile details (name, email, company), account type, creation date, language settings, and feature access information. Use this to verify account existence, check settings, or gather information before updating an account.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account to retrieve (e.g., 'john.smith' or 'client123'). Must match exactly, including any capitalization or special characters. |
</Accordion>

<Accordion title="update_account" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Updates profile information for an existing Duda customer account. Use this to change contact details, language preferences, or company information.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account to update. This identifies which account to modify and cannot itself be changed. |
| `first_name` | string | no | New first name. Leave undefined to keep current value. |
| `last_name` | string | no | New last name. Leave undefined to keep current value. |
| `email` | string | no | New email address. Must be valid email format. Leave undefined to keep current value. |
| `lang` | string | no | New language preference (e.g., 'en', 'es', 'fr'). Leave undefined to keep current value. |
| `company_name` | string | no | New company name. Leave undefined to keep current value. |
</Accordion>

<Accordion title="delete_account" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Permanently deletes a Duda customer account.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account to delete (e.g., 'john.smith'). Must match exactly, including any capitalization. Verify this carefully as deletion cannot be undone. |
</Accordion>

<Accordion title="list_site_permissions" icon="fa-eye">
**Plan:** Team · **Access:** Read-only

Lists the permissions a specific account has for all accessible sites.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account. |
</Accordion>

<Accordion title="grant_site_access" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Grants a customer account initial access to a specific site with a defined set of permissions. Use `updateSitePermissions` to modify existing access. Note: Granting PUBLISH permission requires also granting REPUBLISH and LIMITED_EDITING in the same request.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account. |
| `site_name` | string | yes | The unique name of the site. |
| `permissions` | array of string | yes | An array of permissions to grant (e.g., ['EDIT', 'PUBLISH']). |
</Accordion>

<Accordion title="update_site_permissions" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Updates the existing permissions for a customer account on a specific site. Replaces all current permissions with the provided set. Note: Granting PUBLISH permission requires also granting REPUBLISH and LIMITED_EDITING in the same request.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account. |
| `site_name` | string | yes | The unique name of the site. |
| `permissions` | array of string | yes | The complete new set of permissions for the account on this site. |
</Accordion>

<Accordion title="revoke_site_access" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Revokes a customer account's access to a specific site.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account. |
| `site_name` | string | yes | The unique name of the site. |
</Accordion>

<Accordion title="generate_sso_link" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Generates a Single Sign-On (SSO) link for an account. The link can target either account-level areas (like dashboard) or site-specific areas. The `site_name` parameter is only required for site-specific targets (EDITOR, RESET_SITE, SWITCH_TEMPLATE, etc.), not for dashboard targets.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account. |
| `target` | string | yes | The target area for the SSO link. Site-specific targets include: EDITOR, RESET_SITE, SWITCH_TEMPLATE, SWITCH_TEMPLATE_WITH_AI, SWITCH_GENERATE_TEMPLATE_CONTENT, RESET_BASIC, STORE_MANAGEMENT, SITE_OVERVIEW, STATS, SITE_SEO_OVERVIEW. One of: `EDITOR`, `RESET_SITE`, `SWITCH_TEMPLATE`, `SWITCH_TEMPLATE_WITH_AI`, `SWITCH_GENERATE_TEMPLATE_CONTENT`, `RESET_BASIC`, `STORE_MANAGEMENT`, `SITE_OVERVIEW`, `STATS`, `SITE_SEO_OVERVIEW`. |
| `site_name` | string | no | The unique name of the site. Required for site-specific targets (EDITOR, RESET_SITE, etc.), but not required for dashboard or other account-level targets. |
</Accordion>

<Accordion title="generate_reset_password_link" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Generates a unique, time-sensitive password reset link for a specific customer account. Returns the URL.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account for which to generate a reset password link. |
</Accordion>

<Accordion title="create_welcome_link" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Generates a unique welcome link for a newly created customer account, redirecting the user to set their initial password. Returns the URL.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account for which to generate the welcome link. |
</Accordion>

<Accordion title="get_client_permission_for_site" icon="fa-eye">
**Plan:** Team · **Access:** Read-only

Retrieves the specific list of assigned site permissions for a single customer account on a single site. Useful for checking specific access levels before attempting actions.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the account. |
| `site_name` | string | yes | The unique name of the site. |
</Accordion>

<Accordion title="list_client_sites" icon="fa-eye">
**Plan:** Team · **Access:** Read-only

Lists sites accessible to a CLIENT/CUSTOMER account that you manage. **ONLY use when working with client accounts that you've granted site access to.** If you want to list YOUR OWN sites, use `list_sites` instead. This is for client/customer management scenarios where you need to see what sites a specific customer account can access.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `account_name` | string | yes | The unique username of the client/customer account. |
</Accordion>

### Blog

<Accordion title="list_blog_posts" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Lists all blog posts for a specific Duda site. Returns posts in order of recency with metadata including title, author, publish status, and unique IDs needed for other blog operations.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site (e.g., 'my-site-123'). This is Duda's internal site identifier. |
| `limit` | integer | no | Number of posts to return per page (default 50). Use a smaller number for quicker response times, or up to 100 for comprehensive listings. |
| `offset` | integer | no | Offset for pagination (e.g., 0 for first page, 50 for second page when limit=50). Use with limit for paginated results. |
</Accordion>

<Accordion title="get_blog_post" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Retrieves complete details for a specific blog post including content, metadata, and publication status. Also attempts to construct the full public URL where the post can be viewed. Note that the post URL will only work if both the post and the site are published.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site (e.g., 'my-site-123'). This is Duda's internal site identifier. |
| `post_id` | string | yes | The unique ID of the blog post (e.g., 'abc123'). This ID is returned when listing posts or creating a new post. |
</Accordion>

<Accordion title="create_blog_post" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Creates professional blog posts on a Duda site. SUGGESTED STRUCTURE (optional guidelines): **Title** - Consider making it SEO-friendly and catchy. **Introduction** - Consider starting with a hook, explain topic importance. **Main Body** - Use subheadings (H2/H3), short paragraphs, examples work well. **Conclusion** - Summarize key points and wrap up the article. REQUIRED: thumbnail_url parameter. SUPPORTS: Rich HTML content and image integration.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site (e.g., 'my-site-123'). This is Duda's internal site identifier. |
| `title` | string | yes | The blog post title - should be SEO-friendly, catchy, and ideally under 70 characters for optimal search visibility. |
| `description` | string | yes | Meta description for SEO - a compelling summary that appears in search results and listings. |
| `content` | string | yes | Create comprehensive, detailed HTML blog content with substantial depth and engaging storytelling. **INTRODUCTION** - Start with a compelling hook (3-4 sentences), explain topic importance and context (2-3 sentences), and preview what readers will discover (2-3 sentences). **MAIN BODY** - Use numbered sections with H2 headings (e.g., "1. |
| `author` | string | no | The name of the blog post author (e.g., 'Jane Smith'). Must not exceed 200 characters. If not provided, may default to the site owner. |
| `main_image_url` | string | no | Hero image for the blog post URL. |
| `thumbnail_url` | string | yes | REQUIRED. Thumbnail image shown in blog listings URL. |
| `layout_id` | string | no | Layout page id for the post, from read_blog's `layouts[].id`. Omit to use the blog's default layout. Only available on flex sites that have blog layouts. |
</Accordion>

<Accordion title="update_blog_post" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates metadata for an existing blog post such as title, author, URL path, SEO fields, tags, images, and publish date.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site (e.g., 'my-site-123'). This is Duda's internal site identifier. |
| `post_id` | string | yes | The unique ID of the blog post to update (e.g., 'abc123'). This ID is returned from list_blog_posts or create_blog_post. |
| `path` | string | no | The URL path/slug for the post (e.g., 'summer-sale-announcement'). Must be unique across the site, contain only URL-safe characters, and not include a leading slash. |
| `publish_date` | string | no | Post publication date in ISO format: YYYY-MM-DD'T'HH:mm:ss (e.g., '2024-06-15T09:30:00'). Can be set to a future date. |
| `title` | string | no | The new title for the blog post (e.g., 'Updated: 10 Essential Web Design Tips'). Must not exceed 200 characters. |
| `author_name` | string | no | The new author name for the blog post (e.g., 'Jane Smith, Senior Designer'). Must not exceed 200 characters. |
| `meta_title` | string | no | The SEO title that appears in browser tabs and search results. If different from the post title, this can be optimized for search engines. |
| `description` | string | no | The new meta description for SEO purposes. This appears in search engine results and should be compelling and relevant to the content. |
| `tags` | array of string | no | An array of tags to categorize the post (e.g., ['design', 'user-experience', 'conversion']). Helps with internal organization and SEO. |
| `no_index` | boolean | no | When set to true, prevents search engines from indexing this specific post. Useful for temporary content or posts not meant for public discovery. |
| `thumbnail` | object | no | Thumbnail/main image for the blog post. |
| `thumbnail.url` | string | yes | The URL of the thumbnail image for the blog post. |
| `thumbnail.alt_text` | string | no | Alt text for the thumbnail image. |
| `main_image` | object | no | Main image for the blog post. |
| `main_image.url` | string | yes | The URL of the main image for the blog post. |
| `layout_id` | string | no | Layout page id to move the post onto, from read_blog's `layouts[].id`. Rejected on sites without blog layouts. |
</Accordion>

<Accordion title="delete_blog_post" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Deletes a specific blog post from a Duda site.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `post_id` | string | yes | The unique ID of the blog post to delete. |
</Accordion>

<Accordion title="publish_blog_post" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Publishes a specific blog post on a Duda site. Supports immediate publishing or scheduled publishing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `post_id` | string | yes | The unique ID of the blog post to publish. |
| `schedulePublishDate` | string | no | Optional: Schedule publication for a future date and time. Format: YYYY-MM-DD'T'HH:mm:ss (e.g., '2024-12-25T08:30:15'). Must be in the future. If provided, the post will be scheduled instead of published immediately. |
</Accordion>

<Accordion title="unpublish_blog_post" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Unpublishes a specific blog post on a Duda site.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `post_id` | string | yes | The unique ID of the blog post to unpublish. |
</Accordion>

<Accordion title="create_blog" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Creates a blog configuration for a specific Duda site. This initializes the blog feature on a site that doesn't have one yet.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site (e.g., 'my-site-123'). This is Duda's internal site identifier. |
| `name` | string | no | The internal name for the blog configuration. |
| `title` | string | no | The display title for the blog. |
| `description` | string | no | The description for the blog. |
</Accordion>

<Accordion title="update_blog" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates the blog configuration for a specific Duda site. Only the fields provided will be updated; other fields remain unchanged.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site (e.g., 'my-site-123'). This is Duda's internal site identifier. |
| `name` | string | no | The internal name for the blog configuration. |
| `title` | string | no | The display title for the blog. |
| `description` | string | no | The description for the blog. |
</Accordion>

<Accordion title="import_blog_posts_from_rss" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Imports every entry of an external RSS/Atom feed (e.g. a WordPress blog's https://example.com/feed) as blog posts on a Duda site. The site must already have a blog: check with read_blog and call create_blog first if it has none. Posts are APPENDED to the existing ones and saved as DRAFTS (use list_blog_posts / publish_blog_post afterwards). Side effects: the blog title is replaced with the feed title and images are copied to the site, so feeds with many images can take several minutes.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site (e.g., 'my-site-123'). This is Duda's internal site identifier. |
| `feed_url` | string | yes | Public URL of the RSS or Atom feed to import (e.g., 'https://example.com/feed'). |
| `layout_id` | string | no | Layout page id for the imported posts, from read_blog's `layouts[].id`. Omit to use the blog's default layout. Only available on flex sites that have blog layouts. |
</Accordion>

<Accordion title="read_blog" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Retrieves the blog configuration for a specific Duda site, including name, title, description, image, image alt text, and — when available — the post layouts (`layouts[]` with `id`, `name`, `default`; empty when the site has no layouts). Use a layout's `id` as `layout_id` in create_blog_post / update_blog_post.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site (e.g., 'my-site-123'). This is Duda's internal site identifier. |
</Accordion>

### Content Library

<Accordion title="get_content_library" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Retrieves business data from the content library of a website. The content library is specifically for business information like contact details, business hours, location data, company description, logo and other business-related images that populate across multiple site elements. This is NOT for updating page content or individual elements - use get_elements for that instead. Content library data is essential for Local Business Schema SEO and automated business info widgets.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name/site alias of an existing website |
</Accordion>

<Accordion title="update_content_library" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates structured business data in the content library for a Duda site.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123') |
| `location_data` | object | no | Primary location data including contact info, hours, address, and schema for SEO structured data. |
| `location_data.phones` | array of object | no |   |
| `location_data.phones[].phoneNumber` | string | yes |   |
| `location_data.phones[].label` | string | no |   |
| `location_data.emails` | array of object | no |   |
| `location_data.emails[].emailAddress` | string | yes |   |
| `location_data.emails[].label` | string | no |   |
| `location_data.schema` | object | no |   |
| `location_data.schema.type` | string | no | Schema.org type (e.g., 'LocalBusiness', 'Restaurant', 'Store') |
| `location_data.schema.custom_fields` | array of object | no | SEO schema custom fields - add schema.org properties not supported by standard fields for better SEO structured data |
| `location_data.social_accounts` | object | no |   |
| `location_data.social_accounts.tripadvisor` | string | no |   |
| `location_data.social_accounts.youtube` | string | no |   |
| `location_data.social_accounts.facebook` | string | no |   |
| `location_data.social_accounts.yelp` | string | no |   |
| `location_data.social_accounts.pinterest` | string | no |   |
| `location_data.social_accounts.google_plus` | string | no |   |
| `location_data.social_accounts.linkedin` | string | no |   |
| `location_data.social_accounts.instagram` | string | no |   |
| `location_data.social_accounts.snapchat` | string | no |   |
| `location_data.social_accounts.twitter` | string | no |   |
| `location_data.social_accounts.rss` | string | no |   |
| `location_data.social_accounts.vimeo` | string | no |   |
| `location_data.social_accounts.reddit` | string | no |   |
| `location_data.social_accounts.tiktok` | string | no |   |
| `location_data.social_accounts.google_my_business` | string | no |   |
| `location_data.social_accounts.foursquare` | string | no |   |
| `location_data.social_accounts.whatsapp` | string | no |   |
| `location_data.address` | object | no |   |
| `location_data.address.streetAddress` | string | no |   |
| `location_data.address.postalCode` | string | no |   |
| `location_data.address.region` | string | no |   |
| `location_data.address.city` | string | no |   |
| `location_data.address.country` | string | no |   |
| `location_data.geo` | object | no |   |
| `location_data.geo.longitude` | string | no |   |
| `location_data.geo.latitude` | string | no |   |
| `location_data.logo_url` | string | no | Location logo URL. |
| `location_data.business_hours` | array of object | no |   |
| `location_data.business_hours[].days` | array of string | no |   |
| `location_data.business_hours[].open` | string | no | Opening time in military time, including the leading zero. |
| `location_data.business_hours[].close` | string | no | Closing time in military time, including the leading zero. |
| `site_texts` | object | no | Website text content. SUPPORTED FIELDS: overview, services, about_us, and custom array. Use custom array with label and text for additional business text content. |
| `site_texts.overview` | string | no | Company or business overview text |
| `site_texts.services` | string | no | Description of services or offerings |
| `site_texts.about_us` | string | no | About us section content |
| `site_texts.custom` | array of object | no | Custom business text fields array for additional content. Each item requires 'label' (max 250 chars) and optional 'text' (max 4000 chars) |
| `site_texts.custom[].label` | string | yes | Display label for the field (required, max 250 characters) |
| `site_texts.custom[].text` | string | no | Text content (optional, max 4000 characters) |
| `business_data` | object | no | Core business information including name, logo, description, and category. Supports image placeholders for logo_url field. |
| `business_data.name` | string | no |   |
| `business_data.logo_url` | string | no | Business logo URL. |
| `business_data.description` | string | no |   |
| `business_data.category` | string | no |   |
| `business_data.service_area` | string | no |   |
| `business_data.tone_of_voice` | string | no | One of CONVERSATIONAL, HUMOROUS, ENTHUSIASTIC, INFORMATIVE, PROFESSIONAL, WITTY or AUTHORITATIVE |
| `site_images` | array of object | no | Array of site images with labels and alt text. Supports image placeholders for url field. |
| `site_images[].label` | string | no |   |
| `site_images[].url` | string | no | Site image URL. |
| `site_images[].alt` | string | no |   |
</Accordion>

<Accordion title="publish_content_library" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

NEVER USE THIS TOOL FOR PUBLISHING WEBSITES OR SITES. This tool is ONLY for publishing business data (contact info, hours, addresses) - NOT for making websites live. When user says 'publish my site' or 'publish the website' or 'make my site live' - DO NOT use this tool. If you don't have access to publish_site tool, tell the user you cannot publish websites and they need to use a different interface or tool that has website publishing capabilities. This tool is exclusively for publishing business information updates after using update_content_library.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). The site must already be published for this to work. |
</Accordion>

### Ecommerce

<Accordion title="get_store_details" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Retrieves the eCommerce store details for a specific Duda site. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
</Accordion>

<Accordion title="create_store" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Creates a NATIVE eCommerce store for a specific Duda site that doesn't have one yet. Only relevant if the site store_type is 'NONE'.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier for the target Site. |
</Accordion>

<Accordion title="list_store_products" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Lists products in the NATIVE eCommerce store for a specific Duda site. Only works for sites with store_type 'NATIVE' in their site details. Filters are combined with AND; the list filters (id, category_id, option_id, customization_id, status, type) match any of the values given.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `limit` | integer | no | The size of the page to be returned (default 50, max 200). |
| `offset` | integer | no | Zero-based offset for elements (0..N). |
| `sort` | string | no | Property to sort by. One of: `title`, `created`, `updated`, `price`, `order`. |
| `direction` | string | no | Order direction for the property specified in sort. Default asc. One of: `asc`, `desc`. |
| `search` | string | no | Match products whose name contains the given string, ignore-case, or whose own or variation sku equals it. |
| `category_id` | array of string | no | Return products assigned to any of the given category ids. Given exactly one category and no explicit sort, products keep their order within that category - unless option_id or several customization_id values are also given. |
| `status` | array of string | no | Return products in any of the given statuses. |
| `type` | array of string | no | Return products of any of the given types. |
| `id` | array of string | no | Return the products with any of the given ids. |
| `option_id` | array of string | no | Return products whose variations use any of the given option ids. |
| `customization_id` | array of string | no | Return products assigned any of the given customization ids. |
| `product_url` | string | no | Return the product whose seo.product_url equals the given slug. |
| `variation_external_id` | string | no | Return the whole product that has a variation with the given external id - note this is the variation's external_id, not the product's own. |
| `created_at.gte` | string | no | Return products whose created_at is at or after the given ISO-8601 timestamp. The offset is required - 2026-01-31T10:15:30Z or 2026-01-31T12:15:30+02:00. |
| `created_at.lte` | string | no | Return products whose created_at is at or before the given ISO-8601 timestamp, offset required. |
| `updated_at.gte` | string | no | Return products whose updated_at is at or after the given ISO-8601 timestamp, offset required. The entry point for incremental sync - unlike created_at it also catches edits of products fetched earlier. |
| `updated_at.lte` | string | no | Return products whose updated_at is at or before the given ISO-8601 timestamp, offset required. |
| `on_sale` | boolean | no | Return products whose compare_at_price is set (true) or unset (false). Variations carry a price difference rather than their own compare_at_price, so this always refers to the product-level price. |
| `has_variations` | boolean | no | Return products that have (true) or do not have (false) variations. |
| `fields` | array of string | no | Root fields of each product to return; the id always comes back. Ask only for what the task needs, e.g. ["name", "prices"] - without it every product comes back whole, variations, options and customizations included. |
</Accordion>

<Accordion title="get_store_product" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Gets details for a specific product in the NATIVE eCommerce store. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `product_id` | string | yes | The unique ID of the product. |
| `fields` | array of string | no | Root fields of each product to return; the id always comes back. Ask only for what the task needs, e.g. ["name", "prices"] - without it every product comes back whole, variations, options and customizations included. |
</Accordion>

<Accordion title="create_store_products" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Creates one or multiple products in the NATIVE eCommerce store. Automatically chooses between single and bulk endpoints based on the number of products. Supports Pexels for images. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `products` | array of object | yes | Array of products to create (1-100 products) |
| `products[].name` | string | yes | Product name. |
| `products[].prices` | array of object | yes | List of prices for given product in different currencies. |
| `products[].description` | string or null | no | Product description (HTML). |
| `products[].sku` | string or null | no | Stock Keeping Unit of given product. |
| `products[].images` | array of object | no | Image list for given product. Rich prompts in URLs will be resolved to actual images. |
| `products[].managed_inventory` | boolean | no | Indicated if this product should have inventory management. Default: `false`. |
| `products[].quantity` | integer | no | Available inventory, relevant only if set on the product is managed inventory as true and product has no variations. |
| `products[].requires_shipping` | boolean | no | Indicated if this product is shippable or not. |
| `products[].seo` | object | no |   |
| `products[].seo.title` | string or null | no | Overridable custom title of the product. |
| `products[].seo.description` | string or null | no | Overridable custom description of the product. |
| `products[].seo.product_url` | string or null | no | Overridable custom url of the product. |
| `products[].status` | string | no | Product visibility status. ACTIVE = available in the store, INACTIVE = visible only in the editor, HIDDEN = not displayed in store. One of: `ACTIVE`, `INACTIVE`, `HIDDEN`. |
| `products[].stock_status` | string | no | [IN_STOCK, OUT_OF_STOCK]. One of: `IN_STOCK`, `OUT_OF_STOCK`. |
| `products[].type` | string | no | [PHYSICAL, DIGITAL, SERVICE, DONATION]. One of: `PHYSICAL`, `DIGITAL`, `SERVICE`, `DONATION`. |
| `products[].customizations` | array of object | no | Customizations to assign to this product, referenced by id. Sets the product's customizations. |
</Accordion>

<Accordion title="update_store_product" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates an existing product in the NATIVE eCommerce store. Supports Pexels for images. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `product_id` | string | yes | The ID of the product to update. |
| `name` | string | no | Product name. |
| `prices` | array of object | no | List of prices for given product in different currencies. Only the first entry is applied - the store's own currency is used. |
| `prices[].price` | string | yes | Price for the product in a specific currency. Min val = 0 |
| `prices[].compare_at_price` | string or null | no | When specified, must be higher than price to indicate a discount. This represents the original price before discount (min val = 0). |
| `prices[].currency` | string | no | Currency code according to ISO 4217, e.g. 'USD'. |
| `description` | string or null | no | Product description (HTML). |
| `sku` | string or null | no | Stock Keeping Unit of given product. |
| `external_id` | string | no | Product external id - the identifier this product carries in the system it was imported from. |
| `managed_inventory` | boolean | no | Indicated if this product should have inventory management. |
| `quantity` | integer | no | Available inventory, relevant only if set on the product is managed inventory as true and product has no variations. |
| `requires_shipping` | boolean | no | Indicated if this product is shippable or not. |
| `seo` | object | no |   |
| `seo.title` | string or null | no | Overridable custom title of the product. |
| `seo.description` | string or null | no | Overridable custom description of the product. |
| `seo.product_url` | string or null | no | Overridable custom url of the product. |
| `status` | string | no | Product visibility status. ACTIVE = available in the store, INACTIVE = visible only in the editor, HIDDEN = not displayed in store. One of: `ACTIVE`, `INACTIVE`, `HIDDEN`. |
| `stock_status` | string | no | [IN_STOCK, OUT_OF_STOCK]. Relevant only when the product has managed inventory. One of: `IN_STOCK`, `OUT_OF_STOCK`. |
| `custom_fields` | array of object | no | Values for the store's custom fields. Replaces the product's current custom field values. |
| `custom_fields[].id` | string | yes | Identifier of an existing custom field of this store. |
| `custom_fields[].value` | string | no | Value for TEXT, PLAIN_TEXT and VIDEO custom fields. Ignored for an IMAGE custom field when `image` is provided. |
| `custom_fields[].image` | object | no | Value for an IMAGE custom field. |
| `custom_fields[].image.url` | string | yes | Direct HTTP/S URL of the image (e.g. 'https://example.com/image.jpg'). Rich image prompts ('image://', 'pexels://', plain search phrases) are NOT resolved here - such a value is stored verbatim. |
| `custom_fields[].image.alt` | string or null | no | Alt-text html attribute for image. |
| `customizations` | array of object | no | Customizations to assign to this product, referenced by id. Replaces the product's current customizations. |
| `customizations[].id` | string | yes | Immutable identifier of an existing customization of this store. |
| `options` | array of object | no | Replaces the product's list of options and their allowed choices (max 20 options). Changing the choices without sending `variations` in the same request regenerates the product's variations and loses their per-variation data. |
| `options[].id` | string | no | Immutable identifier of an existing option; omit to create a new one. |
| `options[].name` | string | no | Displayed option name, e.g. 'Shirt size'. |
| `options[].type` | string | no | [TEXT, COLOR]. One of: `TEXT`, `COLOR`. |
| `options[].choices` | array of object | no | Allowed choices to select from. |
| `variations` | array of object | no | The FULL list of variations, replacing the current one (PUT semantics): fetch the product first, change what you need and send every variation back, otherwise the missing ones are deleted. |
| `variations[].sku` | string | no | Stock Keeping Unit of this variation. |
| `variations[].external_id` | string | no | Variation external id. |
| `variations[].price_difference` | string | no | Amount added to the product price for this variation, e.g. '2.50'. Defaults to '0'. |
| `variations[].quantity` | integer | no | Available inventory of this variation, relevant only when the product has managed inventory. |
| `variations[].status` | string | no | [HIDDEN, ACTIVE]. A hidden variation is not available in the store. Defaults to ACTIVE. One of: `HIDDEN`, `ACTIVE`. |
| `variations[].options` | array of object | no | One choice per product option - together they identify the variation. |
| `variations[].images` | array of object | no | Image list for this variation. URLs must already be real image URLs. |
| `images` | array of object | no | Image list for given product. Rich prompts in URLs will be resolved to actual images. |
| `images[].url` | string | yes | Product image URL. |
| `images[].alt` | string or null | no | Alt-text html attribute for image. |
</Accordion>

<Accordion title="bulk_update_store_products" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates MULTIPLE existing products in the NATIVE eCommerce store in ONE request (up to 100 products per call). ALWAYS prefer this tool over update_store_product whenever more than one product has to change - publishing a freshly imported catalog, flipping requires_shipping / status / stock_status across products, filling in missing descriptions, or applying a sale price to a set of products. Each entry patches one product: product_id plus only the fields to change; omitted fields are left untouched, and different entries may carry different fields.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `products` | array of object | yes | Product patches (1-100). Each entry is a product_id plus the fields to change. |
| `products[].product_id` | string | yes | The ID of the product to update. |
| `products[].name` | string | no | Product name. |
| `products[].prices` | array of object | no | List of prices for given product in different currencies. Only the first entry is applied - the store's own currency is used. |
| `products[].description` | string or null | no | Product description (HTML). |
| `products[].sku` | string or null | no | Stock Keeping Unit of given product. |
| `products[].external_id` | string | no | Product external id - the identifier this product carries in the system it was imported from. |
| `products[].managed_inventory` | boolean | no | Indicated if this product should have inventory management. |
| `products[].quantity` | integer | no | Available inventory, relevant only if set on the product is managed inventory as true and product has no variations. |
| `products[].requires_shipping` | boolean | no | Indicated if this product is shippable or not. |
| `products[].seo` | object | no |   |
| `products[].seo.title` | string or null | no | Overridable custom title of the product. |
| `products[].seo.description` | string or null | no | Overridable custom description of the product. |
| `products[].seo.product_url` | string or null | no | Overridable custom url of the product. |
| `products[].status` | string | no | Product visibility status. ACTIVE = available in the store, INACTIVE = visible only in the editor, HIDDEN = not displayed in store. One of: `ACTIVE`, `INACTIVE`, `HIDDEN`. |
| `products[].stock_status` | string | no | [IN_STOCK, OUT_OF_STOCK]. Relevant only when the product has managed inventory. One of: `IN_STOCK`, `OUT_OF_STOCK`. |
| `products[].custom_fields` | array of object | no | Values for the store's custom fields. Replaces the product's current custom field values. |
| `products[].customizations` | array of object | no | Customizations to assign to this product, referenced by id. Replaces the product's current customizations. |
| `products[].options` | array of object | no | Replaces the product's list of options and their allowed choices (max 20 options). Changing the choices without sending `variations` in the same request regenerates the product's variations and loses their per-variation data. |
| `products[].variations` | array of object | no | The FULL list of variations, replacing the current one (PUT semantics): fetch the product first, change what you need and send every variation back, otherwise the missing ones are deleted. |
| `products[].images` | array of object | no | Image list for given product. URLs must already be real image URLs. |
</Accordion>

<Accordion title="delete_store_product" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Deletes a specific product from the NATIVE eCommerce store. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `product_id` | string | yes | The ID of the product to delete. |
</Accordion>

<Accordion title="get_product_variation" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Get catalog product variation by id from a NATIVE eCommerce store. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier for the target Site. |
| `product_id` | string | yes | The unique identifier for the target Product. |
| `variation_id` | string | yes | The unique identifier for the target Variation. |
</Accordion>

<Accordion title="update_product_variation" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Update catalog product variation by id in a NATIVE eCommerce store. Supports Pexels for variation images. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier for the target Site. |
| `product_id` | string | yes | The unique identifier for the target Product. |
| `variation_id` | string | yes | The unique identifier for the target Variation. |
| `external_id` | string or null | no | External ID for the variation. |
| `images` | array of object | no | Image list for the variation. Rich prompts in URLs will be resolved to actual images. |
| `images[].url` | string | yes | Product variation image URL. |
| `images[].alt` | string or null | no | Alt-text html attribute for image. |
| `price_difference` | string or null | no | Price difference from product price. |
| `quantity` | integer | no | Available inventory. |
| `sku` | string or null | no | Stock keeping unit of the variation. |
| `status` | string | no | Status of the variation [HIDDEN, ACTIVE]. One of: `HIDDEN`, `ACTIVE`. |
</Accordion>

<Accordion title="create_product_customizations" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Creates one or more product customizations in the NATIVE eCommerce store — buyer-input fields (TEXT, CHECKBOX, or FILE) that can be assigned to products. Pass a `customizations` array (1-100); each is created independently (continue-on-error). Per item: `title` (internal name) and `type` are required; `hint` applies to TEXT, `button_label` to FILE, and `choices`/`limitations` to CHECKBOX. Assign them to products via the `customizations` field on create_store_products/update_store_product. Returns a BulkResult: \{ results: [\{ index, status:"created"\|"error", resource?, error? \}] \}.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `customizations` | array of object | yes | Customizations to create (1-100). Each is created independently; `title` and `type` are required per item. |
| `customizations[].type` | string | yes | Customization type: TEXT (free text), CHECKBOX (selectable choices), or FILE (upload). Immutable after creation. One of: `TEXT`, `CHECKBOX`, `FILE`. |
| `customizations[].title` | string | yes | Internal name used by the store owner to manage the customization (e.g. 'T-shirt print'). |
| `customizations[].label` | string | no | Label displayed to site visitors (e.g. 'Enter the text to print'). |
| `customizations[].mandatory` | boolean | no | Whether visitors must fill in this customization. Defaults to false. |
| `customizations[].price` | number | no | Additional price applied when the customization is used. Must be &gt;= 0. |
| `customizations[].hint` | string | no | Placeholder shown to visitors. Allowed only for the TEXT type. |
| `customizations[].button_label` | string | no | Upload button label. Allowed only for the FILE type. |
| `customizations[].choices` | array of object | no | Selectable choices. Required for and allowed only for the CHECKBOX type. On update, replaces existing choices. |
| `customizations[].limitations` | object | no | Selection limitations. Allowed only for the CHECKBOX type. On update, REPLACES the entire limitations object (it is rebuilt upstream, not merged) — always send both min_choices and max_choices together, or an omitted one is cleared. |
| `customizations[].limitations.min_choices` | integer | no | Minimum number of choices a visitor must select. CHECKBOX type only. Must be &gt;= 0. |
| `customizations[].limitations.max_choices` | integer | no | Maximum number of choices a visitor may select. CHECKBOX type only. Must be &gt;= 0. |
</Accordion>

<Accordion title="list_product_customizations" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Lists product customizations in the NATIVE eCommerce store with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call) so you pick correct paths instead of guessing. Default returns a small preview (customization_id, title, type, label, mandatory, price); pass fields=['*'] for the full row (incl. the heavy choices array and limitations). mode='count' returns the total only. Pass customization_id to fetch a single customization by id (folds the old get tool).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `customization_id` | string | no | Fetch a single customization by id (folds the old get_product_customization tool). Wrapped as a one-row result envelope. |
| `fields` | array of string | no | Dot-path fields to return per row. Default: small preview. Use ['*'] for the full row. **Call mode='schema' first to discover valid paths before guessing.** |
| `offset` | integer | no | Zero-based offset for pagination. Use next_offset from the previous response. |
| `limit` | integer | no | Page size (1-100). Default 25. |
| `sort` | string | no | Field to sort by. Only 'title' or 'price' are sortable (they map to customization entity properties); an unsupported field is rejected upstream. One of: `title`, `price`. |
| `direction` | string | no | Sort direction. Default asc. One of: `asc`, `desc`. |
| `mode` | string | no | 'items' (default) returns rows. 'count' returns \{total\}. 'schema' returns the field catalog + filterable/sortable lists, NO API call — use this first to discover available fields. One of: `items`, `count`, `schema`. |
</Accordion>

<Accordion title="update_product_customizations" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates one or more product customizations in the NATIVE eCommerce store. Pass a `customizations` array (1-100); each is updated independently (continue-on-error). Per item: customization_id plus only the fields to change — omitted fields are left unchanged, `type` cannot be changed, and providing `choices`/`limitations` replaces them. An item with no fields to change is reported as an error. Returns a BulkResult: \{ results: [\{ index, status:"updated"\|"error", resource?, error? \}] \}. Only works for sites with store_type 'NATIVE'.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `customizations` | array of object | yes | Customizations to update (1-100). Each item must carry customization_id and at least one field to change. |
| `customizations[].customization_id` | string | yes | The id of the customization to update. |
| `customizations[].title` | string | no | Internal name used by the store owner to manage the customization (e.g. 'T-shirt print'). |
| `customizations[].label` | string | no | Label displayed to site visitors (e.g. 'Enter the text to print'). |
| `customizations[].mandatory` | boolean | no | Whether visitors must fill in this customization. Defaults to false. |
| `customizations[].price` | number | no | Additional price applied when the customization is used. Must be &gt;= 0. |
| `customizations[].hint` | string | no | Placeholder shown to visitors. Allowed only for the TEXT type. |
| `customizations[].button_label` | string | no | Upload button label. Allowed only for the FILE type. |
| `customizations[].choices` | array of object | no | Selectable choices. Required for and allowed only for the CHECKBOX type. On update, replaces existing choices. |
| `customizations[].limitations` | object | no | Selection limitations. Allowed only for the CHECKBOX type. On update, REPLACES the entire limitations object (it is rebuilt upstream, not merged) — always send both min_choices and max_choices together, or an omitted one is cleared. |
| `customizations[].limitations.min_choices` | integer | no | Minimum number of choices a visitor must select. CHECKBOX type only. Must be &gt;= 0. |
| `customizations[].limitations.max_choices` | integer | no | Maximum number of choices a visitor may select. CHECKBOX type only. Must be &gt;= 0. |
</Accordion>

<Accordion title="delete_product_customizations" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Deletes one or more product customizations from the NATIVE eCommerce store. Pass a `customization_ids` array (1-100); each is deleted independently (continue-on-error). Each customization is first detached from any products it is assigned to, then removed. Use list_product_customizations to find the ids. Returns a BulkResult: \{ results: [\{ index, status:"deleted"\|"error", resource?, error? \}] \}. Only works for sites with store_type 'NATIVE'.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `customization_ids` | array of string | yes | Ids of the customizations to delete (1-100). Use list_product_customizations to find them. |
</Accordion>

<Accordion title="list_store_orders" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Lists orders in the NATIVE eCommerce store for a specific Duda site. Full order rows are large: pass `fields` to get only the paths you need (call mode='schema' first for the field catalog, no API call), or fields=['*'] for the full row in a paged envelope. Without `fields` the raw upstream page is returned. mode='count' returns the total only. Filter by placement date with created_at.gte / created_at.lte. Use get_store_order for one order. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `limit` | integer | no | Number of orders to return (default 50, maximum 100). Use with offset for pagination. |
| `offset` | integer | no | Offset for pagination. |
| `sort` | string | no | Sorting fields for orders. One of: `status`, `created`, `paymentstatus`, `invoicenumber`, `total`. |
| `direction` | string | no | Sorting direction for orders. One of: `asc`, `desc`. |
| `created_at.gte` | string | no | Return orders placed at or after the given ISO-8601 timestamp. The offset is required - 2026-01-31T10:15:30Z or 2026-01-31T12:15:30+02:00. |
| `created_at.lte` | string | no | Return orders placed at or before the given ISO-8601 timestamp, offset required. |
| `fields` | array of string | no | Dot-path fields to return per order, e.g. ['id', 'created', 'email', 'total', 'items[*].name', 'items[*].quantity', 'discounts[*].name']. Use ['*'] for the full row. |
| `mode` | string | no | 'items' (default) returns orders. 'count' returns \{total\} for the filters. 'schema' returns the field catalog + filterable/sortable lists, NO API call. One of: `items`, `count`, `schema`. |
</Accordion>

<Accordion title="get_store_order" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Gets details for a specific order in the NATIVE eCommerce store. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `order_id` | string | yes | The unique ID of the order. |
</Accordion>

<Accordion title="update_store_order" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates the status of an existing order in the NATIVE eCommerce store. Only works for sites with store_type 'NATIVE' in their site details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `order_id` | string | yes | The ID of the order to update. |
| `status` | string | no | Status of the order One of: `IN_PROGRESS`, `PROCESSED`, `SHIPPED`, `DELIVERED`, `PENDING`, `CANCELLED`, `DISPATCHED`. |
</Accordion>

### Reporting

<Accordion title="get_site_stats" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Retrieves website analytics and traffic statistics for a specific Duda site. Get visitor data, page views, traffic patterns, geographic/system breakdowns, and AI bot (LLM) visits. Perfect for performance analysis and understanding your site's audience engagement. Traffic results include LLM_VISITS: pages fetched by AI bots such as ChatGPT or Claude, counted separately from the human metrics (VISITS, VISITORS, PAGE_VIEWS). LLM_VISITS is null in geo and system rows, and the human metrics are null in llm rows.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `from_date` | string | no | Start date (format: YYYY-MM-DD, e.g., '2024-01-15'). Defaults to 30 days before 'to' date. |
| `to_date` | string | no | End date (format: YYYY-MM-DD, e.g., '2024-01-31'). Defaults to today. |
| `dimension` | string | no | Dimension to query by: 'system', 'geo', or 'llm' (AI bot visits per LLM). Cannot be used with result='activities'. One of: `system`, `geo`, `llm`. |
| `result` | string | no | Type of metrics: 'traffic' or 'activities'. Defaults to 'traffic'. Cannot use 'activities' with dimension. One of: `traffic`, `activities`. Default: `"traffic"`. |
| `dateGranularity` | string | no | Granularity for traffic results: 'DAYS', 'WEEKS', 'MONTHS', or 'YEARS'. One of: `DAYS`, `WEEKS`, `MONTHS`, `YEARS`. |
</Accordion>

<Accordion title="get_site_activities" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Retrieves an activity log showing recent actions and events for a specific Duda site (like publishes, form submissions, edits, etc.). Perfect for tracking site changes, debugging issues, or monitoring site activity. Allows filtering by activity type and date range.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `activities` | array of string | no | Filter by specific activity types (e.g., ['site_published', 'page_created']). Pass all values to get all activities. |
| `limit` | integer | no | Number of activities to return (default 100). |
| `offset` | integer | no | Offset for pagination. |
| `from_date` | string | no | Start date (format: YYYY-MM-DD, e.g., '2024-01-15'). |
| `to_date` | string | no | End date (format: YYYY-MM-DD, e.g., '2024-01-31'). |
</Accordion>

<Accordion title="list_form_submissions" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Lists form submissions and leads captured from contact forms on a specific Duda site. Essential for lead generation analysis, customer inquiry management, and understanding visitor engagement with your contact forms. Filter by form type, date range, or view all submissions.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `form_title` | string | no | Filter submissions by a specific form title. |
| `from` | string | no | Start date (format: YYYY-MM-DD, e.g., '2016-03-01'). |
| `to` | string | no | End date (format: YYYY-MM-DD, e.g., '2016-03-31'). |
| `limit` | integer | no | Number of submissions to return (default 100). |
| `offset` | integer | no | Offset for pagination. |
</Accordion>

<Accordion title="published_sites_by_date" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

**PREFERRED TOOL** for getting recently published sites. Use this instead of `list_sites` when asked for recent sites, random sites for demos, or current work. Much more efficient than browsing through all sites. Returns sites that were published within the specified number of days from today, going backwards in time - these are your most actively managed sites.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `lastDays` | integer | no | The number of days in the past to look for published sites (defaults to 7). For example, lastDays=7 returns sites published in the last 7 days including today. Default: `7`. |
</Accordion>

<Accordion title="created_sites_by_date" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

**PREFERRED TOOL** for getting recently created sites. Use this instead of `list_sites` when asked for recent sites, random sites for demos, or your newest work. Much more efficient than browsing through all sites. Returns sites created within specified time periods - these are your most recent projects. BEHAVIOR: If no parameters are specified, sites created within the last 7 days including today are returned. If just a 'from_date' is specified, sites created in the 7 day period including with the date provided are returned.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `from_date` | string | no | Start date (YYYY-MM-DD). If only 'from_date' is specified, sites created in the 7 day period including 'from_date' are returned. |
| `to_date` | string | no | End date (YYYY-MM-DD). If only 'to_date' is specified, sites created in the 7 day period prior to 'to_date' are returned. |
</Accordion>

### Sites

<Accordion title="list_sites" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

List Duda sites with server-side filters and field projection. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call, paid once per conversation) so you can pick correct dot paths instead of guessing. Default returns a small preview (site_name, site_default_domain, publish_status, creation_date, last_published_date); pass fields=['*'] for the full row. mode='count' returns the total only. Use get_site_details(site_name) when you have an id and want one row.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | array of string | no | Dot-path fields to return per row. Default: small preview. Use ['*'] for the full row. Example: ['site_name','site_business_info.business_name','site_seo.title']. **Call mode='schema' first to discover valid paths before guessing.** |
| `status` | array of string | no | Filter by publish_status. Comma-joined server-side. |
| `labels` | array of string | no | Filter by label names (exact match, comma-joined server-side). Example: ['AI','Editor 2.0']. |
| `created_after` | string | no | ISO date or datetime. Returns sites created on or after this time. |
| `created_before` | string | no | ISO date or datetime. Returns sites created on or before this time. |
| `published_after` | string | no | ISO date or datetime. Returns sites last published on or after this time. |
| `published_before` | string | no | ISO date or datetime. Returns sites last published on or before this time. |
| `sort` | string | no | Sort field. Default 'created'. One of: `created`, `published`. |
| `direction` | string | no | Sort direction. Default 'desc'. One of: `asc`, `desc`. |
| `limit` | integer | no | Page size, default 25, max 200. |
| `offset` | integer | no | Pagination offset. Use the next_offset value from the previous response. |
| `mode` | string | no | 'items' (default) returns rows. 'count' returns \{total\} (one cheap upstream call). 'schema' returns the field catalog + filterable/sortable lists, NO API call — use this first to discover available fields before constructing `fields=[...]`. One of: `items`, `count`, `schema`. |
</Accordion>

<Accordion title="get_site_details" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Retrieves comprehensive information about a specific Duda site including domains, publishing status, business details, SEO settings, and editor URLs. You can look up a site using either its internal site_name or an associated domain. Results include direct links to edit, preview, and manage the site. Pass fields to get only the fields you need: to find the site_name of a domain, call it with domain and fields ['site_name'].

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | no | The site's unique Duda identifier (e.g., 'a1b2c3d4'). Omit it when you look up the site by domain. |
| `domain` | string | no | Search for a site by its domain name instead of site_name. You can provide: (1) A bare domain (e.g., 'example.com'), (2) A subdomain (e.g., 'store.example.com'), or (3) A full URL (e.g., 'https://www.example.com/products'). |
| `fields` | array of string | no | Dot-path fields to return, e.g. ['site_name'] or ['site_name','site_business_info.business_name']. Returns compact JSON with only those fields; ['*'] returns the whole record. |
</Accordion>

<Accordion title="publish_site" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Publishes a Duda site, making all recent changes live to visitors. This takes all updates made in the editor (pages, content, design changes) and pushes them to the live version of the site.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site to publish (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
</Accordion>

<Accordion title="unpublish_site" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Takes a Duda site offline by removing it from public access. After unpublishing, visitors will receive an error when trying to access the site domains. The site remains intact in the editor and can be republished later. Use this for sites under construction, discontinued sites, or temporary maintenance. DO NOT USE THIS TOOL when user asks to publish a site.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site to unpublish (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
</Accordion>

<Accordion title="create_or_generate_site" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Creates a new Duda website with explicit user choice between template-based creation, AI generation from scratch, AI customization from an existing template, or a Duda Vibe site.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `creation_method` | string | yes | REQUIRED. The method to use for creating the site, chosen explicitly by the user. One of: `template`, `AI`, `populate template with AI`, `vibe`. |
| `template_alias` | string | no | REQUIRED when creation_method='populate template with AI'. OPTIONAL when creation_method='template': The template_alias of the template to use as the starting point, as returned by list_templates. |
| `default_domain_prefix` | string | no | The display name for the site that will appear in the Duda site dashboard. Must be between 4-44 characters long. |
| `business_data` | object | no | REQUIRED when creation_method='AI' or creation_method='populate template with AI': Business information object containing essential details for AI site generation/customization. Minimum required: name, description, category. |
| `business_data.name` | string | yes | REQUIRED when creation_method='AI' or creation_method='populate template with AI': The business name - used for site title and branding. |
| `business_data.description` | string | yes | REQUIRED when creation_method='AI' or creation_method='populate template with AI': Description of the business - used to generate relevant content and layout. Maximum 5000 characters. |
| `business_data.category` | string | yes | REQUIRED when creation_method='AI' or creation_method='populate template with AI': Category of the business (e.g., 'restaurant', 'retail', 'service', 'portfolio') - influences site structure and features. Maximum 500 characters. |
| `business_data.logo_url` | string | no | OPTIONAL when creation_method='AI' or creation_method='populate template with AI': Direct URL to the business logo (must be a valid, directly accessible URL). |
| `lang` | string | no | HIGHLY RECOMMENDED when creation_method='AI' or creation_method='populate template with AI': Language code for generated site content and interface. Must be one of the supported language codes. Defaults to English ('en') if not specified. One of: `en`, `es`, `pt`, `fr`, `de`, `tr`, `en_gb`, `it`, `nl`, `ar`, `ca`, `da`, `el`, `es_ar`, `es-mx`, `fi`, `he`, `is`, `ko`, `lt`, `lv`, `nb`, `pl`, `ro`, `ru`, `sv`, `vi`, `zh`, `zh-tw`, `pt-pt`. |
| `additional_ai_context` | object | no | USEFUL when creation_method='AI': Additional context to guide AI generation. Include max_pages to specify the number of pages to generate. |
| `additional_ai_context.max_pages` | integer | no | Number of pages to be generated. Minimum is 1, Maximum is 10. |
| `customize_ai_context` | object | no | OPTIONAL, only used when creation_method='populate template with AI': Additional instructions to guide AI customization of template content. |
| `customize_ai_context.instructions` | string | no | Free-text AI instructions for how the site should look and feel. Can include guidance about specific content, keywords, images, colors, tone, style, and priorities. |
| `theme` | object | no | REQUIRED when creation_method='AI'. OPTIONAL when creation_method='populate template with AI': Theme configuration object to control the visual appearance including colors and typography for different heading levels and breakpoints. |
| `theme.colors` | array of object | yes | REQUIRED: Theme color palette for the website. |
| `theme.colors[].id` | string | yes | Color identifier in format 'color_&lt;number&gt;' (e.g., 'color_1', 'color_2') |
| `theme.colors[].value` | string | yes | Color value (e.g., hex code) |
| `theme.colors[].label` | string | yes | Color label |
| `theme.h1` | object | no |   |
| `theme.h1.font_family` | string | no |   |
| `theme.h1.font_size` | string | no |   |
| `theme.h1.font_weight` | string | no |   |
| `theme.h1.color` | string | no |   |
| `theme.h1.line_height` | string | no |   |
| `theme.h1.letter_spacing` | string | no |   |
| `theme.h1.text_decoration` | string | no |   |
| `theme.h1.font_style` | string | no |   |
| `theme.h1.breakpoints` | object | no |   |
| `theme.h1.breakpoints.mobile` | object | no |   |
| `theme.h1.breakpoints.tablet` | object | no |   |
| `theme.h2` | any | no |   |
| `theme.h3` | any | no |   |
| `theme.h4` | any | no |   |
| `theme.h5` | any | no |   |
| `theme.h6` | any | no |   |
| `theme.paragraph` | any | no |   |
| `theme.default` | any | no |   |
</Accordion>

### Templates

<Accordion title="list_templates" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Lists available Duda website templates that can be used to create new sites. Returns template metadata including template_alias (use it with create_or_generate_site), name and preview images. You can filter templates by language, blog functionality, eCommerce capabilities, AI populate-content eligibility, editor type, page count, and more. Supports sorting and pagination for comprehensive template discovery.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | Number of templates to return (default 100, maximum 200). Use smaller values for faster responses or pagination. Examples: 50 for quick browsing, 100 for comprehensive results. |
| `offset` | integer | no | Starting position for pagination (default 0). Use with limit for paginated results. Example: offset=100 with limit=50 returns templates 101-150. |
| `language` | string | no | Filter templates by language code (e.g., 'en' for English, 'es' for Spanish, 'fr' for French). Only templates designed for the specified language will be returned. |
| `has_blog` | boolean | no | Filter templates by blog functionality. Set to true to only return templates with built-in blog/content management features. Set to false to exclude blog templates. |
| `has_store` | boolean | no | Filter templates by eCommerce functionality. Set to true to return templates with store capabilities. Set to false to exclude store templates. |
| `populate_with_ai_enabled` | boolean | no | Filter templates by AI populate-content flow eligibility. Set to true to return only templates enabled for AI populate-content. Set to false to exclude those templates. |
| `store_type` | string | no | Filter templates by store type. 'NATIVE' for templates with Duda's built-in eCommerce functionality, 'THIRDPARTY' for templates with third-party store integrations (e.g., Snipcart). One of: `NATIVE`, `THIRDPARTY`. |
| `editor` | string | no | Filter templates by editor type. 'ADVANCED' for classic advanced editor templates, 'ADVANCED-2.0' for the newer advanced editor version templates, 'VIBE' for Duda Vibe templates (use them with create_or_generate_site creation_method='vibe'). One of: `ADVANCED`, `ADVANCED-2.0`, `VIBE`. |
| `type` | string | no | Filter by template type. 'DUDA' for official Duda-created templates, 'CUSTOM' for user-created custom templates. One of: `DUDA`, `CUSTOM`. |
| `page_count` | integer | no | Return templates with an exact page count. Use this to find templates with a specific number of pages. |
| `page_count_gte` | integer | no | Return templates with a minimum number of pages (greater than or equal to). Use for finding templates with at least this many pages. |
| `page_count_lte` | integer | no | Return templates with a maximum number of pages (less than or equal to). Use for finding simpler templates with fewer pages. |
| `name_contains` | string | no | Perform a text-based search within template names. Use this to find templates containing specific keywords in their names. |
| `sort` | string | no | Choose sorting field. Currently only 'NAME' is supported for alphabetical sorting by template name. One of: `NAME`. |
| `direction` | string | no | Choose direction of sort. 'ASC' for ascending (A-Z), 'DESC' for descending (Z-A). Only works when sort parameter is provided. One of: `ASC`, `DESC`. |
| `categories` | string | no | Filters by one or more category labels (comma-separated). |
</Accordion>

### Pages

<Accordion title="list_pages" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Get details of all Pages of a Site. If page_uuid is provided, gets details for that specific page instead. Returns page metadata including title, path, SEO settings, and UUID.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target Site (e.g., 'my-site-123'). Required for accessing any page data. |
| `page_uuid` | string | no | Optional. The unique UUID of a specific page (e.g., 'a1b2c3d4...'). If provided, only this page's details will be fetched instead of listing all pages. |
</Accordion>

<Accordion title="update_page_settings" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates page metadata and settings for an existing Duda site page.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique site identifier (e.g., 'a1b2c3d4'). |
| `page_uuid` | string | yes | The unique page identifier (e.g., '12345678-abcd-1234-efgh-123456789abc'). |
| `title` | string | no | New page title for navigation and headers. |
| `path` | string | no | New URL path without leading slash (e.g., 'about-us'). Must be unique and URL-safe. Cannot change for home page. |
| `seo` | object | no | SEO settings - partial update, only specified fields change. |
| `seo.title` | string | no | SEO title for browser tabs and search results (50-60 chars recommended). |
| `seo.description` | string | no | Meta description for search results (150-160 chars recommended). |
| `seo.no_index` | boolean | no | True to prevent search engine indexing. Default: `false`. |
| `seo.og_image` | string | no | Open Graph image URL for social sharing (1200x630px recommended). |
| `draft_status` | string | no | STAGED_DRAFT: publishes with site. DRAFT: unpublishes immediately. Home page cannot be DRAFT. One of: `STAGED_DRAFT`, `DRAFT`. Default: `"STAGED_DRAFT"`. |
| `collection_name` | string | no | Rebind a dynamic page to a different existing collection. Dynamic pages only - the API rejects it for a regular page. Use create_page with collection_name to make a new dynamic page. |
</Accordion>

<Accordion title="create_page" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Creates a new Page on a site. The page is added to the end of site navigation. Pass collection_name to create a dynamic page instead of a regular one. Returns the created page with its UUID.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique site identifier (e.g., 'my-site-123'). |
| `page_title` | string | yes | Page title for navigation and menus (e.g., 'About Us'). |
| `page_path` | string | yes | URL path without leading slash (e.g., 'about-us'). Must be unique and URL-safe. |
| `seo` | object | no | SEO settings for better search visibility and social sharing. |
| `seo.title` | string | no | SEO title for browser/search results. Defaults to page_title. |
| `seo.description` | string | no | SEO description (50-160 chars recommended). |
| `seo.no_index` | boolean | no | True to prevent search engine indexing. Default: `false`. |
| `seo.og_image` | string | no | Open Graph image URL for social sharing. |
| `draft_status` | string | no | STAGED_DRAFT: publishes with site. DRAFT: stays unpublished. One of: `STAGED_DRAFT`, `DRAFT`. Default: `"STAGED_DRAFT"`. |
| `collection_name` | string | no | Name of an existing collection to bind the page to. Providing it creates a dynamic page, which renders one URL per collection row. Omit for a regular static page. |
</Accordion>

<Accordion title="duplicate_page" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Creates a new page as an exact copy of an existing page: the same sections, layout, styles and content, under a new title and path. Use it when the user wants a duplicate or a 1:1 copy of a page, then change only what the user asked for. To build a page with its own content in another page's style, create the page and write it instead. The copy is added to the end of site navigation. Returns the new page with its UUID.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique site identifier (e.g., 'my-site-123'). |
| `page_uuid` | string | yes | The UUID of the page to copy (from list_pages). |
| `page_title` | string | yes | Title of the new page (e.g., 'About Us 2'). |
| `page_path` | string | yes | URL path of the new page without leading slash (e.g., 'about-us-2'). Must be unique and URL-safe. |
| `seo` | object | no | SEO settings of the new page. |
| `seo.title` | string | no | SEO title of the new page. |
| `seo.description` | string | no | SEO description of the new page (50-160 chars recommended). |
| `draft_status` | string | no | STAGED_DRAFT: publishes with site. DRAFT: stays unpublished. One of: `STAGED_DRAFT`, `DRAFT`. |
</Accordion>

<Accordion title="delete_page" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Permanently deletes a page from a Duda site, including all of its content. Deletes one page per call; to delete several pages call it once per page.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique site identifier (e.g., 'my-site-123'). |
| `page_uuid` | string | yes | The UUID of the page to delete (from list_pages). |
</Accordion>

### Popups

<Accordion title="list_popups" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Get all popups of a Site. If popup_uuid is provided, gets details for that specific popup instead. Returns popup name, UUID, path, and styles (styles present on Editor 2.0/flex sites only). path is the popup page path with no leading slash (e.g. 'popup-1'; a translated popup carries a locale prefix, e.g. 'de/newsletterPopup'). Popups do not appear in list_pages; use this tool to discover them. Popup content (text, images, widgets) is edited separately via the popup's UUID.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target Site (e.g., 'a1b2c3d4'). |
| `popup_uuid` | string | no | Optional. The unique UUID of a specific popup. If provided, only this popup's details will be fetched instead of listing all popups. |
</Accordion>

<Accordion title="create_popup" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Creates a new popup on a site. Returns the created popup with its UUID and path. The popup is created with default template content; styles cannot be set on create — use update_popup_settings afterwards to change appearance (Editor 2.0/flex sites only). Popup triggers/timing are managed via personalization rules, not here.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique site identifier (e.g., 'a1b2c3d4'). |
| `name` | string | yes | Popup display name shown in the editor (e.g., 'Newsletter Signup'). |
</Accordion>

<Accordion title="update_popup_settings" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates a popup's name and/or appearance styles. Does NOT modify popup content (text, images, widgets). Omitted top-level fields are left unchanged.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique site identifier (e.g., 'a1b2c3d4'). |
| `popup_uuid` | string | yes | The unique popup identifier (from list_popups or create_popup). |
| `name` | string | no | New popup display name. |
| `styles` | object | no | Popup appearance. Replaces ALL managed style properties when provided — include every field to keep. |
| `styles.size` | object | no | Popup width/height (desktop / base appearance). |
| `styles.size.width` | string | no | CSS length (px/%/vw/vh/em/rem) or 'auto'. |
| `styles.size.height` | string | no | CSS length (px/%/vw/vh/em/rem) or 'auto'. |
| `styles.background` | object | no | Popup background, shared across all devices: color and/or image. |
| `styles.background.color` | string | no | Background color: hex (#rgb/#rrggbb/#rrggbbaa) or rgb()/rgba(). |
| `styles.background.image` | object | no | Background image; url is required when provided. |
| `styles.background.image.url` | string | yes | Bare image URL (no url() wrapper). |
| `styles.background.image.display_mode` | string | no | One of: `COVER`, `CONTAIN`, `TILE`, `NO_REPEAT`. |
| `styles.background.image.position` | string | no | One of: `top left`, `top center`, `top right`, `center left`, `center center`, `center right`, `bottom left`, `bottom center`, `bottom right`. |
| `styles.background.image.attachment` | string | no | 'fixed' enables the scroll effect. One of: `fixed`, `initial`. |
| `styles.border` | object | no |   |
| `styles.border.width` | string | no | CSS border-width: 1-4 space-separated px values. border-style: solid is applied automatically. |
| `styles.border.color` | string | no | CSS border-color: 1-4 colors. |
| `styles.border.radius` | string | no | CSS border-radius: 1-4 space-separated px/% values. |
| `styles.box_shadow` | string | no | CSS box-shadow value, e.g. 'rgba(0, 0, 0, 0.25) 3px 0px 11px 0px'. |
| `styles.padding` | string | no | CSS padding: 1-4 space-separated lengths. |
| `styles.animation` | string | no | Popup entry animation; 'none' disables it. One of: `none`, `bounce`, `flash`, `pulse`, `rubberBand`, `shake`, `swing`, `tada`, `wobble`, `bounceIn`, `bounceInLeft`, `bounceInRight`, `fadeIn`, `fadeInLeft`, `fadeInRight`, `fadeInUp`, `flipInX`, `flipInY`, `rotateIn`, `rotateInDownLeft`, `rotateInDownRight`, `rotateInUpLeft`, `rotateInUpRight`, `rollIn`, `zoomIn`, `zoomInUp`, `slideInDown`, `slideInLeft`, `slideInRight`. |
| `styles.breakpoint_overrides` | object | no | Per-breakpoint size overrides. The base style is the desktop appearance. |
| `styles.breakpoint_overrides.tablet` | object | no |   |
| `styles.breakpoint_overrides.tablet.size` | any | no |   |
| `styles.breakpoint_overrides.mobile` | object | no |   |
| `styles.breakpoint_overrides.mobile.size` | any | no |   |
</Accordion>

<Accordion title="delete_popup" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Permanently deletes a popup from a site, including its content (text, images, widgets) and styles. This cannot be undone, so confirm with the user before calling unless they explicitly asked to delete this popup. Use list_popups to find the popup UUID. Personalization rules that trigger the popup are not deleted here.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique site identifier (e.g., 'a1b2c3d4'). |
| `popup_uuid` | string | yes | The unique popup identifier to delete (from list_popups or create_popup). |
</Accordion>

### Collections

<Accordion title="get_collections" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Get all collections that exist on this website, or get detailed information about a specific collection including its fields and row data. Collections are structured data containers that can be used to create dynamic content on Duda sites.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | no | Optional. Name of the collection (e.g., 'Team_Members', 'Products'). If provided, returns detailed information about this specific collection including its structure and all row data. |
</Accordion>

<Accordion title="create_collection" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Create a new collection within a site. Collections organize structured data that can be displayed on your Duda website.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `name` | string | yes | The name of the collection (e.g., 'Team_Members', 'Products'). Must not start with '$' and should be descriptive of the data it will contain. |
| `customer_lock` | string | no | The lock state of the collection. 'unlocked': fully editable, 'structure_locked': fields cannot be modified but data can, 'locked': cannot be modified at all. Default: 'unlocked'. One of: `unlocked`, `structure_locked`, `locked`. Default: `"unlocked"`. |
| `static_page_bindable` | boolean | no | When true, allows collection data to be connected to widgets on a non-dynamic page. Default: false (only usable in dynamic pages). Default: `false`. |
| `fields` | array of object | no | Array of field definitions for this collection. Required for internal collections. Field types |
| `fields[].name` | string | yes | The name of the collection field. |
| `fields[].type` | string | yes | The data type for this field. |
| `fields[].multi_select_options` | array of string | no | If the type is 'MULTI_SELECT', provide an array of options. |
| `external_details` | object or null | no | Configuration for external collections. Leave null/undefined for internal collections. For external collections, set 'enabled' to true and provide 'external_endpoint' to create a collection that pulls data from an external API. |
| `external_details.enabled` | boolean | no | A boolean flag to specify the collection as external (true) vs. an internal (false) collection. Default: `false`. |
| `external_details.external_endpoint` | string | no | An absolute URI pointing to the data for the collection. Required if enabled is true. |
| `external_details.external_id` | string | no | Value that can be used to revalidate the collection cache without using a site alias. |
| `external_details.authorization_header_value` | string | no | Value to be sent in the Authorization header. This value should include the authorization scheme e.g., Basic or Bearer. |
| `external_details.page_item_url_field` | string | no | The name of a field in the collection. The value of this field will be used to generate the URL slug for dynamic pages generated by this collection. Field should not exceed 350 characters - excess characters will be trimmed from the URL. |
| `external_details.collection_data_json_path` | string | no | Path to the root of the collection data within the collection endpoint response. If no path is provided the entire response will be used as collection data. |
| `external_details.custom_headers` | array of object | no | Array of custom headers to be sent along with the data request from Duda. |
| `external_details.custom_headers[].name` | string | yes | Header name. |
| `external_details.custom_headers[].values` | array of string | yes | Array of header values. |
</Accordion>

<Accordion title="create_collection_rows" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Add data rows to a collection.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the collection to add the row(s) to (e.g., 'Team_Members'). The collection must already exist on the site. |
| `rows` | array of object | yes | Array of row objects to create. Example: [\{"data": \{"name": "John Smith", "price": 25.99\}\}]. See CollectionRowDataSchema for field formatting requirements. |
| `rows[].data` | object | yes | The actual data for the row. get_collections reports each field's type; format its value by that type: • TEXT fields: an HTML string - the rich-text editor's markup • PLAIN_TEXT / EMAIL / PHONE fields: a plain string • LINK fields: a URL string; a link to another page of the site is "/page-alias", and an anchor on it "/page-alias#anchor" • NUMBER fields: an actual number, NOT a string • BOOLEAN fields: true or false • IMAGE fields: Image URL. |
| `rows[].page_item_url` | string | no | For internal collections, the row's dynamic page URL, unique in the collection: 'web-design' makes the row's page /&lt;dynamic page&gt;/web-design. Leave it out and the row gets the next free number (1, 2, 3...) as its URL. |
| `rows[].status` | string | no | Where the row shows up: ACTIVE - on the published site and in the editor; PREVIEW - in the editor only; DRAFT - on neither, the row stays in the collection table only. Leave it out to create the row as ACTIVE. One of: `ACTIVE`, `PREVIEW`, `DRAFT`. |
</Accordion>

<Accordion title="update_collection_rows" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Update existing collection rows.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the collection where rows will be updated (e.g., 'Team_Members'). |
| `rows` | array of object | yes | Array of row objects to update. Example: [\{"id": "a1b2c3", "data": \{"name": "Jane Doe", "price": 30.99\}\}]. |
| `rows[].id` | string | yes | The ID of the row to update. |
| `rows[].data` | object | yes | The actual data for the row. get_collections reports each field's type; format its value by that type: • TEXT fields: an HTML string - the rich-text editor's markup • PLAIN_TEXT / EMAIL / PHONE fields: a plain string • LINK fields: a URL string; a link to another page of the site is "/page-alias", and an anchor on it "/page-alias#anchor" • NUMBER fields: an actual number, NOT a string • BOOLEAN fields: true or false • IMAGE fields: Image URL. |
| `rows[].page_item_url` | string | no | For internal collections, you can update the dynamic page URL by passing this property. |
| `rows[].status` | string | no | Where the row shows up: ACTIVE - on the published site and in the editor; PREVIEW - in the editor only; DRAFT - on neither, the row stays in the collection table only. Leave it out to keep the row's current status. One of: `ACTIVE`, `PREVIEW`, `DRAFT`. |
</Accordion>

<Accordion title="patch_collection_rows" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Change some fields of existing collection rows and leave the rest as they are. Prefer this over update_collection_rows whenever you are not deliberately rewriting a whole row: a field you leave out keeps its stored value, so you neither have to read the row first nor risk blanking the fields you did not mention. Send a field as null to clear it. Up to 100 rows per call, and each row is answered on its own - one refused row does not discard the others.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the collection whose rows are patched (e.g., 'Team_Members'). |
| `rows` | array of object | yes | Array of row patches. Example: [\{"id": "a1b2c3", "data": \{"price": 30.99\}\}] changes the price and touches nothing else. |
| `rows[].id` | string | yes | The ID of the row to patch. |
| `rows[].data` | object | yes | The fields to change, and only those. A field you leave out keeps the value it has; a field sent as null is cleared - except a BOOLEAN, which a null sets to false, as a collection has no empty state for one. |
| `rows[].page_item_url` | string | no | For internal collections, the dynamic page URL. Leave it out to keep the current one. |
| `rows[].status` | string | no | Where the row shows up: ACTIVE - on the published site and in the editor; PREVIEW - in the editor only; DRAFT - on neither, the row stays in the collection table only. Leave it out to keep the row's current status. One of: `ACTIVE`, `PREVIEW`, `DRAFT`. |
</Accordion>

<Accordion title="delete_collection_rows" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Delete existing rows of data from a collection.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the collection from which rows will be deleted (e.g., 'Team_Members'). |
| `row_ids` | array of string | yes | An array of row IDs to delete. These IDs are returned when rows are created or can be obtained from get_collections. Example: ['a1b2c3', 'd4e5f6'] |
</Accordion>

<Accordion title="create_collection_fields" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Add new field(s) to an existing collection. Collection fields define the structure and data types of your collection.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the collection to add the field(s) to (e.g., 'Team_Members', 'Products'). The collection must already exist on the site. |
| `fields` | array of object | yes | Array of field definitions to add to the collection. Each field must have a unique name (not starting with '$'), a valid UPPERCASE type (see CollectionFieldSchema), and optionally multi_select_options if type is 'MULTI_SELECT'. |
| `fields[].name` | string | yes | The name of the collection field. |
| `fields[].type` | string | yes | The data type for this field. |
| `fields[].multi_select_options` | array of string | no | If the type is 'MULTI_SELECT', provide an array of options. |
</Accordion>

<Accordion title="update_collection_field" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Update an existing field in a collection. Currently, only the field name can be updated. The field name must not start with '$' and must be unique within the collection.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the collection containing the field to update (e.g., 'Team_Members', 'Products'). |
| `field_name` | string | yes | Current name of the field to update. Must not start with '$'. |
| `new_field_name` | string | yes | New name for the field. Must not start with '$' and should be unique within the collection. |
</Accordion>

<Accordion title="delete_collection_field" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Delete an existing field from a collection.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the collection containing the field to delete (e.g., 'Team_Members', 'Products'). |
| `field_name` | string | yes | Name of the field to delete. This action will permanently remove the field and all its data from all collection rows. |
</Accordion>

<Accordion title="delete_collection" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Delete an entire collection, including all of its fields and rows.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the collection to delete (e.g., 'Team_Members', 'Products'). This action permanently removes the collection and all its data. |
</Accordion>

<Accordion title="publish_collection" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Publish a collection so its latest schema and data changes go live on the site. Use after creating or editing a collection's fields or rows to make those changes visible on the published website.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the collection to publish (e.g., 'Team_Members', 'Products'). The collection must already exist on the site. |
</Accordion>

<Accordion title="update_collection" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Update an existing collection's settings: rename it, change its lock state, toggle non-dynamic-page binding, adjust external-collection connection details, or change the external refresh interval. Provide the collection's current name in collection_name and only the fields you want to change. At least one changeable field is required.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Current name of the collection to update (e.g., 'Team_Members', 'Products'). |
| `name` | string | no | New name for the collection. Must not start with '$'. Omit to keep the current name. |
| `customer_lock` | string | no | The lock state of the collection. 'unlocked': fully editable, 'structure_locked': fields cannot be modified but data can, 'locked': cannot be modified at all. One of: `unlocked`, `structure_locked`, `locked`. |
| `static_page_bindable` | boolean | no | When true, allows collection data to be connected to widgets on a non-dynamic page. |
| `external_details` | object | no | Connection settings for external collections (external_endpoint, authorization, custom headers, etc.). Only relevant for external collections. |
| `external_details.enabled` | boolean | no | A boolean flag to specify the collection as external (true) vs. an internal (false) collection. Default: `false`. |
| `external_details.external_endpoint` | string | no | An absolute URI pointing to the data for the collection. Required if enabled is true. |
| `external_details.external_id` | string | no | Value that can be used to revalidate the collection cache without using a site alias. |
| `external_details.authorization_header_value` | string | no | Value to be sent in the Authorization header. This value should include the authorization scheme e.g., Basic or Bearer. |
| `external_details.page_item_url_field` | string | no | The name of a field in the collection. The value of this field will be used to generate the URL slug for dynamic pages generated by this collection. Field should not exceed 350 characters - excess characters will be trimmed from the URL. |
| `external_details.collection_data_json_path` | string | no | Path to the root of the collection data within the collection endpoint response. If no path is provided the entire response will be used as collection data. |
| `external_details.custom_headers` | array of object | no | Array of custom headers to be sent along with the data request from Duda. |
| `external_details.custom_headers[].name` | string | yes | Header name. |
| `external_details.custom_headers[].values` | array of string | yes | Array of header values. |
| `base_refresh_interval` | string | no | How often an external collection refreshes, as an ISO-8601 duration (e.g., 'PT1H' for hourly). Top-level setting, not part of external_details. |
</Accordion>

<Accordion title="revalidate_collection" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Invalidate an external collection's cached data so it is re-fetched from the source URL the next time it is needed for rendering (e.g. when a widget that uses it loads). The data is not fetched immediately. Use when the upstream data has changed and you want the next fetch to pick it up instead of waiting for the scheduled refresh.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | A valid site name of an existing website (e.g., 'my-site-123'). |
| `collection_name` | string | yes | Name of the external collection to refresh (e.g., 'Team_Members', 'Products'). The collection must already exist on the site. |
</Accordion>

### Theme

<Accordion title="get_site_theme" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Retrieves the complete GLOBAL DESIGN configuration for a Duda website. This returns the site-wide theme settings that control the appearance of ALL elements of each type across the ENTIRE site - for example, ALL H1 headings, ALL paragraphs, etc. Returns a JSON object containing the global color palette and global text configuration with detailed information including color identifiers, RGBA values, descriptive labels and typography settings. This is NOT for individual elements, sections, or pages - it's for the global, site-level design system.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g., "my-site-123"). |
</Accordion>

<Accordion title="update_site_theme" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Updates the complete theme configuration for a Duda website with STRICT VALIDATION. This modifies the site-wide theme settings that control the appearance of ALL elements of each type across the ENTIRE site. Supports updating colors and text styles.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g., "my-site-123"). |
| `theme` | object | yes | Complete theme object containing colors, and text properties. Text styles have strict validation - ensure all values match the allowed formats and enums. |
| `theme.colors` | array of object | no | Array of global color objects with id, value (hex format), and label that will be applied site-wide |
| `theme.colors[].id` | string | yes | Unique identifier for the color (must match existing IDs) |
| `theme.colors[].value` | string or null | yes | Hex color code (e.g., "#FF5733") or null for unused colors |
| `theme.colors[].label` | string or null | yes | Descriptive name for the color (e.g., "Primary Blue") or null for unused colors |
| `theme.text` | object or null | no | Global text styles configuration with STRICT VALIDATION RULES. Colors must be RGBA, RGB, hex, or CSS variables. Font weight supports numeric strings "100"-"900" and keywords "bold", "normal". Font size must use px units only. |
| `theme.text.default` | object | no | Default text style applied to all text elements |
| `theme.text.default.font_family` | string | no | Single font name only - NO FALLBACKS SUPPORTED. Use only one font name (e.g., "Inter", "Arial", "Roboto"). Cannot be empty string. |
| `theme.text.default.color` | string or null | no | Text color in RGBA format (e.g., "rgba(255, 0, 0, 1)"), RGB format (e.g., "rgb(255, 0, 0)"), hex format (e.g., "#FF0000" or "#F00"), or CSS variable (e.g., "var(--color_1)"). Named colors (red, blue) and transparent are NOT allowed. |
| `theme.text.default.font_weight` | string or null | no | Font weight as numeric string or keyword. Valid values: "100"-"900", "bold", "normal". One of: `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `bold`, `normal`. |
| `theme.text.default.font_style` | string or null | no | Font style. Only "normal" or "italic" allowed. One of: `normal`, `italic`. |
| `theme.text.default.text_decoration` | string or null | no | Text decoration. Only "underline" or "none" allowed. One of: `underline`, `none`. |
| `theme.text.default.text_direction` | string or null | no | Text direction. Only "ltr" or "rtl" allowed. One of: `ltr`, `rtl`. |
| `theme.text.default.line_height` | string or null | no | Line height as "normal" or unitless number (e.g., "1.5", "2"). Values with units like "24px" or "1.5em" are NOT allowed. Can be omitted from object. |
| `theme.text.default.letter_spacing` | string or null | no | Letter spacing as "initial", "0", or value with em units (e.g., "0.1em", "-0.05em"). Other units like "1px" are NOT allowed. Can be omitted from object. |
| `theme.text.default.font_size` | string or null | no | Font size with px units only (e.g., "16px", "12.5px"). Negative values and other units (em, rem, %) are NOT allowed. Keywords like "small", "medium" are NOT allowed. |
| `theme.text.default.text_transform` | string or null | no | Text transform. Only "uppercase" or "none" allowed. One of: `uppercase`, `none`. |
| `theme.text.default.mobile_font_size` | string or null | no | Mobile breakpoint font size |
| `theme.text.default.tablet_font_size` | string or null | no | Tablet breakpoint font size |
| `theme.text.paragraph` | any | no |   |
| `theme.text.h1` | any | no |   |
| `theme.text.h2` | any | no |   |
| `theme.text.h3` | any | no |   |
| `theme.text.h4` | any | no |   |
| `theme.text.h5` | any | no |   |
| `theme.text.h6` | any | no |   |
</Accordion>

### URL Rules

<Accordion title="list_url_rules" icon="fa-eye">
**Plan:** Team · **Access:** Read-only

Gets all URL rules for a specific Duda site. URL rules allow you to create redirects, rewrites, and other URL management configurations for your site. This is useful for SEO, migration from old URLs, and managing site navigation.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
</Accordion>

<Accordion title="create_url_rule" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Creates a new URL rule for a specific Duda site. URL rules allow you to set up redirects, rewrites, and other URL management configurations. This is useful for SEO purposes, handling old URLs after site migrations, and managing site navigation flow.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `source` | string | yes | Source path of the redirect (e.g., '/old-page', '/products/*'). Use wildcards (*) for pattern matching. |
| `target` | string | yes | Target page path, URL or page name (e.g., '/new-page', '/products/$1', 'https://example.com'). Use $1, $2, etc. to reference wildcard captures from source. |
| `response_code` | integer | yes | HTTP response code for the redirect. Common values: 301 (permanent redirect), 302 (temporary redirect), 200 (rewrite without redirect). |
</Accordion>

<Accordion title="update_url_rule" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Updates an existing URL rule for a specific Duda site. This allows you to modify the source path, target destination, or response code of an existing redirect/rewrite rule. Useful for maintaining URL management configurations and updating redirect behaviors.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `rule_id` | string | yes | The unique identifier of the URL rule to update. Use list_url_rules to find existing rule IDs. |
| `source` | string | no | Updated source path of the redirect (e.g., '/old-page', '/products/*'). Use wildcards (*) for pattern matching. |
| `target` | string | no | Updated target page path, URL or page name (e.g., '/new-page', '/products/$1', 'https://example.com'). Use $1, $2, etc. to reference wildcard captures from source. |
| `response_code` | integer | no | Updated HTTP response code for the redirect. Common values: 301 (permanent redirect), 302 (temporary redirect), 200 (rewrite without redirect). |
</Accordion>

<Accordion title="delete_url_rule" icon="fa-pen-to-square">
**Plan:** Team · **Access:** Write (destructive)

Deletes an existing URL rule from a specific Duda site.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `rule_id` | string | yes | The unique identifier of the URL rule to delete. Use list_url_rules to find existing rule IDs. |
</Accordion>

### Booking

<Accordion title="create_booking" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Creates a booking organization for a Duda site. Use this to initialize booking for a site before managing its status or related booking resources.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
</Accordion>

<Accordion title="get_booking" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Get the booking organization for a Duda site. Retrieves the current booking organization details.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
</Accordion>

<Accordion title="update_booking_status" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Update the status of a booking organization for a Duda site. Sets the organization status to ACTIVE or SOFT_DELETED.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `status` | string | yes | The new booking organization status. Allowed values: 'ACTIVE' or 'SOFT_DELETED'. One of: `ACTIVE`, `SOFT_DELETED`. |
</Accordion>

<Accordion title="get_booking_appt_types" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Get all appointment types for a Duda site, or get detailed information about a specific appointment type by its ID. Returns paginated results with appointment type metadata including name, description, duration, and creation/update timestamps.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `id` | string | no | Optional. The unique identifier of the appointment type (e.g., '01JZ83QB5MQFRMXWAVQ55C648W'). If provided, returns detailed information about this specific appointment type. If omitted, returns list of all appointment types. |
</Accordion>

<Accordion title="create_booking_appt_type" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Create a new appointment type for a Duda site. Appointment types define the different kinds of appointments that can be booked (e.g., 'Consultation', 'Follow-up', 'Initial Meeting').

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `name` | string | yes | Name of the appointment type (e.g., 'Consultation', 'Follow-up', 'Initial Meeting'). |
| `duration` | integer | yes | Duration of the appointment in minutes (e.g., 30, 60, 90). |
| `description` | string | no | Optional description of the appointment type (e.g., 'Initial consultation with our team'). |
| `pricing_type` | string | no | Pricing type of the appointment. Defaults to 'FREE' if not provided. Use 'PAID' for paid appointments, which requires price_info to be set. One of: `FREE`, `PAID`. |
| `price_info` | object | no | Price information for paid appointments. Required when pricing_type is 'PAID'. Contains base_price as a string. |
| `price_info.base_price` | string | yes | Base price of the appointment as a string (e.g., '50.00', '100.0'). Required when pricing_type is 'PAID'. |
</Accordion>

<Accordion title="update_booking_appt_type" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Update an existing appointment type for a Duda site. This is a partial update - only the fields provided will be modified. Appointment types define the different kinds of appointments that can be booked (e.g., 'Consultation', 'Follow-up', 'Initial Meeting').

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `id` | string | yes | The unique identifier of the appointment type (e.g., '01JZ83QB5MQFRMXWAVQ55C648W'). Use get_booking_appt_types to find this if needed. |
| `name` | string | no | Name of the appointment type (e.g., 'Consultation', 'Follow-up', 'Initial Meeting'). |
| `duration` | integer | no | Duration of the appointment in minutes (e.g., 30, 60, 90). |
| `description` | string | no | Optional description of the appointment type (e.g., 'Initial consultation with our team'). Can be set to empty string when updating to remove description. |
| `pricing_type` | string | no | Pricing type of the appointment. Use 'PAID' for paid appointments, which requires price_info to be set. One of: `FREE`, `PAID`. |
| `price_info` | object | no | Price information for paid appointments. Required when pricing_type is 'PAID'. Contains base_price as a string. |
| `price_info.base_price` | string | yes | Base price of the appointment as a string (e.g., '50.00', '100.0'). Required when pricing_type is 'PAID'. |
</Accordion>

<Accordion title="delete_booking_appt_type" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Delete an appointment type from a Duda site. Removes the appointment type so it can no longer be booked.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `id` | string | yes | The unique identifier of the appointment type (e.g., '01JZ83QB5MQFRMXWAVQ55C648W'). Use get_booking_appt_types to find this if needed. |
</Accordion>

<Accordion title="list_booking_appts" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Lists all appointments for a Duda site with comprehensive filtering and sorting options. Returns paginated results with appointment details including attendees, hosts, status, times, and metadata. Supports filtering by status, date ranges, attendee email, appointment type, staff members, and more. Also supports sorting by start time, end time, creation time, or update time.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `limit` | integer | no | Maximum number of results to return per page. Use with offset for pagination. |
| `offset` | integer | no | Number of results to skip. Use with limit for pagination (e.g., offset=0 for first page, offset=100 for second page when limit=100). |
| `status` | array of string | no | Filter appointments by status. Can specify multiple statuses (e.g., ['upcoming', 'unconfirmed']). |
| `attendee_email` | string | no | Filter appointments by attendee email address. |
| `appointment_uid` | string | no | Filter appointments by booking unique identifier (UID). |
| `appointment_types` | array of string | no | Filter appointments by appointment type identifiers. Provide an array of appointment type IDs. |
| `staff_member_ids` | array of string | no | Filter appointments by staff member identifiers. Provide an array of staff member IDs. |
| `after_start` | string | no | Filter appointments with start time after this date string (ISO-8601 format, e.g., '2025-01-01T00:00:00Z'). |
| `before_end` | string | no | Filter appointments with end time before this date string (ISO-8601 format, e.g., '2025-12-31T23:59:59Z'). |
| `after_created_at` | string | no | Filter appointments created after this date string (ISO-8601 format, e.g., '2025-01-01T00:00:00Z'). |
| `before_created_at` | string | no | Filter appointments created before this date string (ISO-8601 format, e.g., '2025-12-31T23:59:59Z'). |
| `after_updated_at` | string | no | Filter appointments updated after this date string (ISO-8601 format, e.g., '2025-01-01T00:00:00Z'). |
| `before_updated_at` | string | no | Filter appointments updated before this date string (ISO-8601 format, e.g., '2025-12-31T23:59:59Z'). |
| `sort_start` | string | no | Sort results by start time in ascending ('asc') or descending ('desc') order. One of: `asc`, `desc`. |
| `sort_end` | string | no | Sort results by end time in ascending ('asc') or descending ('desc') order. One of: `asc`, `desc`. |
| `sort_created` | string | no | Sort results by creation time (when booking was made) in ascending ('asc') or descending ('desc') order. One of: `asc`, `desc`. |
| `sort_updated_at` | string | no | Sort results by updated time (when booking status changes) in ascending ('asc') or descending ('desc') order. One of: `asc`, `desc`. |
</Accordion>

<Accordion title="get_booking_staff" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Get all staff members for a Duda site, or get detailed information about a specific staff member by their ID. Returns paginated results with staff member metadata including name, email, ID, and associated account name.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `id` | string | no | Optional. The unique identifier of the staff member (e.g., 'staff-member-123'). If provided, returns detailed information about this specific staff member. If omitted, returns list of all staff members. |
</Accordion>

<Accordion title="create_booking_staff" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Create a new staff member for a Duda site. Staff members are the people who can host appointments. You can create a staff member by providing either an account_name (which will use the account's name and email) or by providing name and email directly.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `account_name` | string | no | Name of a Duda account that will be associated with the staff member. If provided, name and email become optional. For more information about accounts, see: https://developer.duda.co/reference/accounts-object |
| `email` | string or any | no | Email address of the staff member. Required if account_name is not provided. Optional if account_name is provided - if omitted, email will be resolved from the account. |
| `name` | string or any | no | Full name of the staff member. Required if account_name is not provided. Optional if account_name is provided - if omitted, name will be resolved from the account (firstName + lastName, or account name). |
| `timezone` | string | no | Timezone of the staff member for scheduling (e.g., 'America/New_York', 'Europe/London', 'UTC'). If not provided, defaults to 'America/New_York'. Used to initialize default schedule and availability settings. |
</Accordion>

<Accordion title="update_booking_staff" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Update an existing staff member for a Duda site. This is a partial update - only the fields provided will be modified. Staff members are the people who can host appointments.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `id` | string | yes | The unique identifier of the staff member (e.g., 'staff-member-123'). Use get_booking_staff to find this if needed. |
| `account_name` | string | no | Name of a Duda account that will be associated with the staff member. This is a partial update - only fields provided will be updated. If omitted, the account association remains unchanged. |
| `email` | string or any | no | Email address of the staff member. This is a partial update - if omitted, the email remains unchanged. Must be a valid email address format if provided. |
| `name` | string or any | no | Full name of the staff member. This is a partial update - if omitted, the name remains unchanged. Cannot be empty or blank if provided. |
</Accordion>

<Accordion title="delete_booking_staff" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Delete a staff member from a Duda site. Removes the staff member so they can no longer host appointments.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `id` | string | yes | The unique identifier of the staff member (e.g., 'staff-member-123'). Use get_booking_staff to find this if needed. |
</Accordion>

<Accordion title="get_booking_staff_avail" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Get the availability schedule for a specific staff member. Availability schedules include regular availability slots (days of week and time ranges) and schedule overrides for specific dates (e.g., holidays, special hours).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `id` | string | yes | The unique identifier of the staff member (e.g., 'staff-member-123'). Use get_booking_staff to find this if needed. |
</Accordion>

<Accordion title="update_booking_staff_avail" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Update the availability schedule for a specific staff member. Availability schedules include regular availability slots (days of week and time ranges) and schedule overrides for specific dates (e.g., holidays, special hours). This is a partial update - only the fields provided will be modified.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the site (e.g., 'a1b2c3d4'). Use list_sites to find this if needed. |
| `id` | string | yes | The unique identifier of the staff member (e.g., 'staff-member-123'). Use get_booking_staff to find this if needed. |
| `time_zone` | string | no | Timezone for the schedule (e.g., 'America/New_York', 'Europe/London', 'Asia/Jerusalem'). If omitted, the timezone remains unchanged. |
| `availability` | array of object | no | Regular availability slots defining weekly recurring availability. Each slot specifies days of the week and time ranges. If omitted, the availability slots remain unchanged. |
| `availability[].days` | array of string | yes | Days of the week for this availability slot (e.g., ['Monday', 'Tuesday', 'Wednesday']). |
| `availability[].start_time` | string | yes | Start time in HH:MM format (e.g., '09:00'). |
| `availability[].end_time` | string | yes | End time in HH:MM format (e.g., '17:00'). |
| `overrides` | array of object | no | Schedule overrides for specific dates (e.g., holidays, special hours). These override the regular availability for the specified dates. If omitted, the overrides remain unchanged. |
| `overrides[].date` | string | yes | Date for the override in YYYY-MM-DD format (e.g., '2024-12-25'). |
| `overrides[].start_time` | string | yes | Start time for the override in HH:MM format (e.g., '10:00'). |
| `overrides[].end_time` | string | yes | End time for the override in HH:MM format (e.g., '14:00'). |
</Accordion>

### Marketing

<Accordion title="marketing_list_custom_fields" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Lists all marketing custom field definitions for a site. Custom fields extend the contact schema with site-specific attributes (e.g., "Loyalty Tier", "VIP", "Birthday").

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
</Accordion>

<Accordion title="marketing_create_custom_field" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Creates a new marketing custom field definition. Choose field_type carefully — it determines validation and which segment operators are available.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `field_key` | string | yes | Immutable machine-readable key. Pattern: ^[a-z][a-z0-9_]\{0,63\}$. Example: "tier". |
| `field_label` | string | yes | Human-readable label shown in the marketing UI. Example: "Customer Tier". |
| `field_type` | string | yes | One of: `text`, `number`, `date`, `boolean`, `dropdown`. |
| `dropdown_options` | array of string | no | Required when field_type is "dropdown" — allowed option values. |
| `is_required` | boolean | no |   |
| `display_order` | integer | no |   |
</Accordion>

<Accordion title="marketing_update_custom_field" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Updates a marketing custom field definition. field_key and field_type cannot be changed after creation.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `custom_field_id` | string | yes |   |
| `field_label` | string | no |   |
| `dropdown_options` | array of string | no |   |
| `is_required` | boolean | no |   |
| `display_order` | integer | no |   |
</Accordion>

<Accordion title="marketing_delete_custom_field" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Deletes a marketing custom field definition. DESTRUCTIVE — removes the field value from all contacts. Set confirm_field_key to the field's exact field_key; the tool fetches the field and errors if they disagree. Refused with a 409 while the site still uses the field, and nothing is deleted: "Custom field is used by a segment, an automation or a scheduled campaign and cannot be deleted." That sentence names the three kinds of row that can hold a field, not which one held this one. A segment holds it when its rules test the field, whatever the segment's state.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `custom_field_id` | string | yes |   |
| `confirm_field_key` | string | yes | Must equal the field's exact field_key — a guard against deleting the wrong field. |
</Accordion>

<Accordion title="marketing_find_contacts" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Find marketing contacts with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call) so you pick correct paths instead of guessing. Default returns a small preview (contact_id, email, first_name, last_name, status, email_subscription_status); pass fields=['*'] for the full row (incl. heavy custom_fields, notes, address). mode='count' returns the total only. Pass contact_id to fetch one contact by id.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `contact_id` | string | no | Fetch a single contact by id (folds the old get tool). Wrapped as a one-row result envelope. |
| `segment_id` | string | no | List contacts currently matching this segment (GET /segments/\{id\}/contacts). offset must be a multiple of limit. |
| `fields` | array of string | no | Dot-path fields to return per row. Default: small preview. Use ['*'] for the full row. **Call mode='schema' first to discover valid paths before guessing.** |
| `search` | string | no | Fuzzy search across name, email, and company. Upstream-supported. |
| `sort` | string | no | Sort field. Default created_at. One of: `created_at`, `name`, `email`, `company`, `first_name`, `last_name`, `lifecycle_stage`, `lead_source`, `status`, `last_contacted_at`, `next_follow_up_at`. |
| `direction` | string | no | Sort direction. Default desc. One of: `asc`, `desc`. |
| `limit` | integer | no | Page size, default 25, max 200. |
| `offset` | integer | no | Pagination offset. Use next_offset from the previous response. |
| `mode` | string | no | 'items' (default) returns rows. 'count' returns \{total\}. 'schema' returns the field catalog + filterable/sortable lists, NO API call — use this first to discover available fields. One of: `items`, `count`, `schema`. |
</Accordion>

<Accordion title="marketing_import_contacts" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Creates contacts in bulk (1–100 per call, continue-on-error). N=1 is just a one-element array. Each contact may carry a `subscription` block to set per-channel (email/sms) marketing consent at import time. CONSENT CHECK — do this before calling: (1) The details state explicit opt-in per channel (e.g. "opted in to marketing emails", an opt-in column naming a channel) → map it onto each contact's `subscription` exactly as given. (2) Consent info is ambiguous (e.g.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `contacts` | array of object | yes |   |
| `contacts[].email` | string | yes |   |
| `contacts[].first_name` | string or null | no |   |
| `contacts[].last_name` | string or null | no |   |
| `contacts[].phone` | string or null | no |   |
| `contacts[].company` | string or null | no |   |
| `contacts[].tags` | array of string | no |   |
| `contacts[].notes` | string or null | no |   |
| `contacts[].address` | object | no |   |
| `contacts[].address.street` | string or null | no |   |
| `contacts[].address.city` | string or null | no |   |
| `contacts[].address.region` | string or null | no |   |
| `contacts[].address.postal_code` | string or null | no |   |
| `contacts[].address.country` | string or null | no |   |
| `contacts[].lead_source` | string | no | One of: `form`, `booking`, `store`, `import`, `manual`, `referral`, `membership`. |
| `contacts[].lifecycle_stage` | string | no | One of: `lead`, `prospect`, `customer`, `churned`. |
| `contacts[].custom_fields` | object | no | Map of custom_field_id -&gt; value. Field types must match the custom field definition. |
| `contacts[].subscription` | object | no | Per-channel marketing consent. COMPLIANCE: only set "subscribed" for contacts with explicit opt-in. Omit a channel to leave it unchanged. |
| `contacts[].subscription.email` | string | no | One of: `subscribed`, `unsubscribed`. |
| `contacts[].subscription.sms` | string | no | One of: `subscribed`, `unsubscribed`. |
</Accordion>

<Accordion title="marketing_update_contacts" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Updates contacts in bulk (1–100 per call, continue-on-error, PATCH semantics). Each item needs contact_id plus only the fields to change. Contact ids come from marketing_find_contacts: search by email to resolve an address to its id. Include a `subscription` block to change per-channel (email/sms) marketing consent. Tags (labels on a contact) change through add_tags and remove_tags, which leave every other tag on the contact in place. Returns a BulkResult.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `contacts` | array of object | yes |   |
| `contacts[].contact_id` | string | yes |   |
| `contacts[].first_name` | string or null | no |   |
| `contacts[].last_name` | string or null | no |   |
| `contacts[].phone` | string or null | no |   |
| `contacts[].company` | string or null | no |   |
| `contacts[].add_tags` | array of string | no | Tags to put on the contact. Its other tags stay. |
| `contacts[].remove_tags` | array of string | no | Tags to take off the contact. Its other tags stay. |
| `contacts[].notes` | string or null | no |   |
| `contacts[].address` | object | no |   |
| `contacts[].address.street` | string or null | no |   |
| `contacts[].address.city` | string or null | no |   |
| `contacts[].address.region` | string or null | no |   |
| `contacts[].address.postal_code` | string or null | no |   |
| `contacts[].address.country` | string or null | no |   |
| `contacts[].lead_source` | string | no | One of: `form`, `booking`, `store`, `import`, `manual`, `referral`, `membership`. |
| `contacts[].lifecycle_stage` | string | no | One of: `lead`, `prospect`, `customer`, `churned`. |
| `contacts[].custom_fields` | object | no |   |
| `contacts[].subscription` | object | no | Per-channel marketing consent. COMPLIANCE: only set "subscribed" for contacts with explicit opt-in. Omit a channel to leave it unchanged. |
| `contacts[].subscription.email` | string | no | One of: `subscribed`, `unsubscribed`. |
| `contacts[].subscription.sms` | string | no | One of: `subscribed`, `unsubscribed`. |
</Accordion>

<Accordion title="marketing_delete_contacts" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Permanently deletes contacts by id (1–100). Contact ids come from marketing_find_contacts: search by email to resolve an address to its id. DESTRUCTIVE — set confirm_count to contact_ids.length to proceed; the tool errors if they disagree. Returns a BulkResult: \{ results: [\{ index, status:"deleted"\|"error", error? \}] \}.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `contact_ids` | array of string | yes |   |
| `confirm_count` | integer | yes | Must equal contact_ids.length — a guard against accidental mass deletion. |
</Accordion>

<Accordion title="marketing_set_subscription" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Sets per-channel marketing subscription state for contacts (1–100). Contact ids come from marketing_find_contacts: search by email to resolve an address to its id. Choose a channel (email or sms; default email); subscribed=true grants consent, subscribed=false revokes it — recorded as a consent event via PATCH /contacts/bulk. `subscribed` is deliberately distinct from the lifecycle `status` field (active/archived) on a contact row. COMPLIANCE: only subscribe contacts who have given explicit opt-in. Returns a BulkResult: \{ results: [\{ index, status:"updated"\|"error", resource?, error? \}] \}.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `contact_ids` | array of string | yes |   |
| `channel` | string | no | Channel to set consent on. Defaults to email. One of: `email`, `sms`. Default: `"email"`. |
| `subscribed` | boolean | yes | true = subscribe (compliance: explicit opt-in required); false = unsubscribe. |
</Accordion>

<Accordion title="marketing_find_segments" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Find marketing segments with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call) so you pick correct paths instead of guessing. Default returns a small preview (segment_id, name, segment_type, match_type, contact_count, updated_at); pass fields=['*'] for the full row (incl. the heavy rules condition tree). mode='count' returns the total only. Pass segment_id to fetch one segment by id; to list a segment's member contacts use marketing_find_contacts with segment_id instead.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `segment_id` | string | no | Fetch a single segment by id (folds the old get tool). Wrapped as a one-row result envelope. |
| `fields` | array of string | no | Dot-path fields to return per row. Default: small preview. Use ['*'] for the full row. **Call mode='schema' first to discover valid paths before guessing.** |
| `limit` | integer | no | Page size, default 25, max 200. |
| `offset` | integer | no | Pagination offset. Use next_offset from the previous response. |
| `mode` | string | no | 'items' (default) returns rows. 'count' returns \{total\}. 'schema' returns the field catalog + filterable/sortable lists, NO API call — use this first to discover available fields. One of: `items`, `count`, `schema`. |
</Accordion>

<Accordion title="marketing_create_segment" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Creates a marketing segment. DYNAMIC segments evaluate rules against contacts at query time (rules required). STATIC segments are manually curated (rules must be omitted). Top-level AND/OR is controlled by match_type ("ALL" = AND, "ANY" = OR). For a RELATIVE date window like "created in the last 3 months", use a date condition with operator "in_last", value 3 (the amount), and unit "months" — never an absolute date — so the dynamic segment keeps rolling forward.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `name` | string | yes |   |
| `description` | string or null | no |   |
| `segment_type` | string | yes | One of: `dynamic`, `static`. |
| `match_type` | string | no | "ALL"=AND, "ANY"=OR. Defaults to ALL. (dynamic only) One of: `ALL`, `ANY`. |
| `rules` | object | no | The condition tree. REQUIRED for segment_type="dynamic"; must be omitted for "static". |
| `rules.conditions` | array of object | yes |   |
| `rules.conditions[].type` | `field` | yes |   |
| `rules.conditions[].field` | string | yes | Contact field name (snake_case). tags / lifecycle_stage / lead_source / status / text fields / email_subscription_status / sms_subscription_status (value: subscribed \| unsubscribed \| not_subscribed \| bounced; operators equals / not_equals) / total_order_amount and last_order_amount (the store's order amounts: value a number, operators equals / not_equals / greater_than / less_than / greater_or_equal / less_or_equal; a contact who never ordered compares as 0, so "spent over $500" is greater_than 500 and less_than 10 includes non-buyers). |
| `rules.conditions[].operator` | string | yes |   |
| `rules.conditions[].value` | any | no |   |
</Accordion>

<Accordion title="marketing_update_segment" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Updates a marketing segment. segment_type cannot be changed after creation. A segment whose stored rules hold a nested group (type "group", from before groups were removed) cannot have its rules changed here, because rules must be a flat list: tell the user to edit that segment in the segment editor, and never drop, merge or rewrite its conditions to make the update fit. Its name and description can still be updated without sending rules.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `segment_id` | string | yes |   |
| `name` | string | no |   |
| `description` | string or null | no |   |
| `match_type` | string | no | One of: `ALL`, `ANY`. |
| `rules` | object | no | Wrapper object containing a flat conditions array, combined by the sibling match_type. There are no nested groups: the segment editor shows one match for the whole rule. |
| `rules.conditions` | array of object | yes |   |
| `rules.conditions[].type` | `field` | yes |   |
| `rules.conditions[].field` | string | yes | Contact field name (snake_case). tags / lifecycle_stage / lead_source / status / text fields / email_subscription_status / sms_subscription_status (value: subscribed \| unsubscribed \| not_subscribed \| bounced; operators equals / not_equals) / total_order_amount and last_order_amount (the store's order amounts: value a number, operators equals / not_equals / greater_than / less_than / greater_or_equal / less_or_equal; a contact who never ordered compares as 0, so "spent over $500" is greater_than 500 and less_than 10 includes non-buyers). |
| `rules.conditions[].operator` | string | yes |   |
| `rules.conditions[].value` | any | no |   |
</Accordion>

<Accordion title="marketing_delete_segment" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Deletes a marketing segment. DESTRUCTIVE — set confirm_name to the segment's exact name; the tool fetches the segment and errors if they disagree. Refused with a 409 while something still uses the segment, and nothing is deleted: "Segment is used by an automation (audience or condition) or by a campaign that can still send, and cannot be deleted." The server refuses rather than leaving a dangling reference behind, so a delete either takes the segment or changes nothing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `segment_id` | string | yes |   |
| `confirm_name` | string | yes | Must equal the segment's exact name — a guard against deleting the wrong segment. |
</Accordion>

<Accordion title="marketing_set_segment_members" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Adds contacts to, or removes them from, a STATIC segment's membership (1-100 contacts). member=true adds, member=false removes; removing a contact from a segment does not delete the contact. Only STATIC segments have a membership to set — a DYNAMIC segment's members come from its rules, so this errors for one and marketing_update_segment (rules) is the way to change who it matches. Get the segment id from marketing_find_segments. Contact ids come from marketing_find_contacts: search by email to resolve an address to its id.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `segment_id` | string | yes | The static segment to change. From marketing_find_segments (segment_type must be "static"). |
| `contact_ids` | array of string | yes | Contact ids, not emails. Contact ids come from marketing_find_contacts: search by email to resolve an address to its id. |
| `member` | boolean | yes | true = add the contacts to the segment; false = remove them from it. |
</Accordion>

<Accordion title="marketing_find_email_tmpls" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Find email templates with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog PLUS email_json_spec (block-graph shape, the supported block types, validation rules) and merge_tokens, with NO API call, making it your reference for composing email_json. Default returns a small preview (template_id, name, description, category, subject, thumbnail, updated_at) — the heavy email_json is dropped; pass fields=['*'] to retrieve it for auditing or cloning. mode='count' returns the total only.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `template_id` | string | no | Fetch a single template by id (folds the old get tool). Wrapped as a one-row result envelope; includes email_json when fields=["*"]. |
| `fields` | array of string | no | Dot-path fields to return per row. Default: small preview (no email_json). Use ['*'] for the full row incl. email_json. **Call mode='schema' first to discover valid paths and the email_json contract.** |
| `limit` | integer | no | Page size, default 25, max 200. |
| `offset` | integer | no | Pagination offset. Use next_offset from the previous response. |
| `mode` | string | no | 'items' (default) returns rows. 'count' returns \{total\}. 'schema' returns the field catalog + filterable/sortable + email_json_spec + merge_tokens, NO API call — use this first to discover fields and the email_json contract. One of: `items`, `count`, `schema`. |
</Accordion>

<Accordion title="marketing_create_email_tmpl" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Creates a new email template. For a NEW design call marketing_email_recipe first and fill in its theme-seeded skeleton, then pass the same archetype here so the design check judges the email against that composition. The response carries design_warnings when the saved design falls short; act on them. May be refused with 422 and error_code MarketingContentRejected when the content conflicts with the service's usage requirements; nothing is stored, changed or sent.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `name` | string | yes |   |
| `subject` | string | yes |   |
| `preheader` | string or null | no |   |
| `email_json` | object | no | Structured email content as a block graph. Map&lt;String, Block&gt;. |
| `archetype` | string | no | The marketing_email_recipe archetype (starter id) this email was composed from. Not stored — it lets the design check judge the email against that composition (e.g. a promo with no image, a newsletter with no dividers). |
| `from_template` | string | no | Build this email from a designed template, keeping its layout EXACTLY: pass the library template id from marketing_email_recipe together with slots, and leave email_json out. |
| `slots` | object | no | The copy to write into the template, keyed by block id: \{ "&lt;block_id&gt;": \{ text \| url \| alt \| links \| backgroundImage \} \}. marketing_email_recipe lists every slot with the sample copy it currently holds. |
</Accordion>

<Accordion title="marketing_update_email_tmpl" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Updates an existing email template. Only include fields you want to change. May be refused with 422 and error_code MarketingContentRejected when the content conflicts with the service's usage requirements; nothing is stored, changed or sent. The message names the part to change (the subject, the preview text, the sender name, the sender email address or the message body), or no part when it is the content as a whole, and never the reason: do not guess a reason or give the user one.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `template_id` | string | yes | Template id from marketing_find_email_tmpls — always fetch first; never guess or reuse ids from earlier conversations. |
| `name` | string | no |   |
| `subject` | string | no |   |
| `preheader` | string or null | no |   |
| `email_json` | object | no | Structured email content as a block graph. Map&lt;String, Block&gt;. |
| `archetype` | string | no | The marketing_email_recipe archetype (starter id) this email follows. Not stored — it lets the design check judge the email against that composition. |
| `from_template` | string | no | Build this email from a designed template, keeping its layout EXACTLY: pass the library template id from marketing_email_recipe together with slots, and leave email_json out. |
| `slots` | object | no | The copy to write into the template, keyed by block id: \{ "&lt;block_id&gt;": \{ text \| url \| alt \| links \| backgroundImage \} \}. marketing_email_recipe lists every slot with the sample copy it currently holds. |
</Accordion>

<Accordion title="marketing_delete_email_tmpl" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Deletes an email template. DESTRUCTIVE — set confirm_name to the template's exact name; the tool fetches the template and errors if they disagree.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `template_id` | string | yes |   |
| `confirm_name` | string | yes | Must equal the template's exact name — a guard against deleting the wrong template. |
</Accordion>

<Accordion title="marketing_email_tmpl_library" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Returns the built-in email template library — the designed templates the editor gallery offers — each already seeded with this site's theme and carrying guidance on when its layout fits. Copy is finished sample copy to rewrite; button links are REPLACE_ME placeholders to replace. Prefer marketing_email_recipe, which serves the same templates plus the block guide and composition rules; use this when you need the whole catalogue in one call.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
</Accordion>

<Accordion title="marketing_email_recipe" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Pick a designed template for a NEW marketing email and get its block-graph email_json, already seeded with this site's own theme (fonts, sizes, text and button colors; accent blocks use the primary button colors). Call this BEFORE authoring email_json for a new email (template, campaign or automation step) — it is the design step that stops emails coming out as an unstyled stack of text; never compose email_json from nothing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `archetype` | string | no | Which template to build on — a template id from the catalogue this tool lists. Omit to list the templates with their "when" notes and choose one. |
| `mode` | string | no | 'list' (default when archetype is omitted) returns the template catalogue + block guide. 'skeleton' returns the seeded email_json for the chosen template. One of: `list`, `skeleton`. |
</Accordion>

<Accordion title="marketing_find_campaigns" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Find marketing campaigns with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call) so you pick correct paths instead of guessing. Default returns a small preview (campaign_id, name, type, status, subject, sent_at, scheduled_at, recipient_type); pass fields=['*'] for the full row (incl. heavy email_json up to 256KB, recipient_filter, sender). mode='count' returns the total only. Pass campaign_id to fetch one campaign by id.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `campaign_id` | string | no | Fetch a single campaign by id (folds the old get tool). Wrapped as a one-row result envelope. |
| `fields` | array of string | no | Dot-path fields to return per row. Default: small preview. Use ['*'] for the full row. **Call mode='schema' first to discover valid paths before guessing.** |
| `limit` | integer | no | Page size, default 25, max 200. |
| `offset` | integer | no | Pagination offset. Use next_offset from the previous response. |
| `mode` | string | no | 'items' (default) returns rows. 'count' returns \{total\}. 'schema' returns the field catalog + filterable/sortable lists, NO API call — use this first to discover available fields. One of: `items`, `count`, `schema`. |
</Accordion>

<Accordion title="marketing_create_campaign" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Creates a marketing campaign in draft status. Sending is a separate call to marketing_send_campaign. May be refused with 422 and error_code MarketingContentRejected when the content conflicts with the service's usage requirements; nothing is stored, changed or sent. The message names the part to change (the subject, the preview text, the sender name, the sender email address or the message body), or no part when it is the content as a whole, and never the reason: do not guess a reason or give the user one.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `name` | string | yes |   |
| `type` | string | yes | email or sms. One of: `email`, `sms`. |
| `recipient_type` | string | yes | Who receives this. all=all subscribers, segment=a segment, individual=specific contacts, date_range / trigger. One of: `all`, `individual`, `date_range`, `segment`, `trigger`. |
| `subject` | string | no |   |
| `body` | string | no | The SMS message text, for type=sms campaigns. Ignored for email, whose body is derived server-side from email_json. |
| `email_json` | object | no | Structured email content as a block graph. Map&lt;String, Block&gt;. |
| `segment_id` | string | no | Required when recipient_type is segment. |
| `recipient_ids` | array of string | no | Required when recipient_type is individual. |
| `recipient_filter` | object | no |   |
| `sender` | object | no |   |
| `sender.first_name` | string or null | no |   |
| `sender.last_name` | string or null | no |   |
| `sender.email_prefix` | string or null | no | Local part of from-address; brand domain appended server-side. |
| `sender.reply_to_email` | string or null | no |   |
| `archetype` | string | no | The marketing_email_recipe archetype (starter id) this email was composed from. Not stored — it lets the design check judge the email against that composition. |
| `from_template` | string | no | Build this email from a designed template, keeping its layout EXACTLY: pass the library template id from marketing_email_recipe together with slots, and leave email_json out. |
| `slots` | object | no | The copy to write into the template, keyed by block id: \{ "&lt;block_id&gt;": \{ text \| url \| alt \| links \| backgroundImage \} \}. marketing_email_recipe lists every slot with the sample copy it currently holds. |
</Accordion>

<Accordion title="marketing_update_campaign" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Updates a campaign in draft status. Sent campaigns are immutable. May be refused with 422 and error_code MarketingContentRejected when the content conflicts with the service's usage requirements; nothing is stored, changed or sent. The message names the part to change (the subject, the preview text, the sender name, the sender email address or the message body), or no part when it is the content as a whole, and never the reason: do not guess a reason or give the user one.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `campaign_id` | string | yes | Campaign id from marketing_find_campaigns — always fetch first; never guess or reuse ids from earlier conversations. |
| `name` | string | no |   |
| `recipient_type` | string | no | One of: `all`, `individual`, `date_range`, `segment`, `trigger`. |
| `subject` | string | no |   |
| `body` | string | no | The SMS message text, for type=sms campaigns. Ignored for email, whose body is derived server-side from email_json. |
| `email_json` | object | no | Structured email content as a block graph. Map&lt;String, Block&gt;. |
| `segment_id` | string | no |   |
| `recipient_ids` | array of string | no |   |
| `recipient_filter` | object | no |   |
| `sender` | object | no |   |
| `sender.first_name` | string or null | no |   |
| `sender.last_name` | string or null | no |   |
| `sender.email_prefix` | string or null | no | Local part of from-address; brand domain appended server-side. |
| `sender.reply_to_email` | string or null | no |   |
| `archetype` | string | no | The marketing_email_recipe archetype (starter id) this email follows. Not stored — it lets the design check judge the email against that composition. |
| `from_template` | string | no | Build this email from a designed template, keeping its layout EXACTLY: pass the library template id from marketing_email_recipe together with slots, and leave email_json out. |
| `slots` | object | no | The copy to write into the template, keyed by block id: \{ "&lt;block_id&gt;": \{ text \| url \| alt \| links \| backgroundImage \} \}. marketing_email_recipe lists every slot with the sample copy it currently holds. |
</Accordion>

<Accordion title="marketing_delete_campaign" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Deletes a campaign. DESTRUCTIVE — set confirm_name to the campaign's exact name; the tool fetches the campaign and errors if they disagree.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `campaign_id` | string | yes | Campaign id from marketing_find_campaigns — always fetch first; never guess or reuse ids from earlier conversations. |
| `confirm_name` | string | yes | Must equal the campaign's exact name — a guard against deleting the wrong campaign. |
</Accordion>

<Accordion title="marketing_send_campaign" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

DESTRUCTIVE: Sends a draft campaign (using its already-configured recipient_type / segment_id / recipient_ids) to real subscribers. ALWAYS require explicit user confirmation including recipient count before calling. Optionally schedule with send_at (ISO 8601 UTC). An SMS campaign reaches a recipient only 09:00-20:00 Monday-Saturday in that recipient's local time; a number with several time zones must be inside the window in all of them. Every recipient is checked at the moment the campaign runs, and a recipient outside the window at that moment fails and is not retried.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `campaign_id` | string | yes | Campaign id from marketing_find_campaigns — always fetch first; never guess or reuse ids from earlier conversations. |
| `send_at` | string | no | UTC ISO 8601 timestamp; must be in the future. Omit to send immediately. |
</Accordion>

<Accordion title="marketing_find_automations" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Find marketing automations with field projection and pagination. **Before projecting fields you have not used before, call mode='schema' first** — it returns the full field catalog (no API call) so you pick correct paths instead of guessing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | no | Fetch a single automation by id (folds the old get tool). Wrapped as a one-row result envelope; includes steps when fields=["*"]. |
| `fields` | array of string | no | Dot-path fields to return per row. Default: small preview. Use ['*'] for the full row. **Call mode='schema' first to discover valid paths before guessing.** |
| `limit` | integer | no | Page size, default 25, max 200. |
| `offset` | integer | no | Pagination offset. Use next_offset from the previous response. |
| `mode` | string | no | 'items' (default) returns rows. 'count' returns \{total\}. 'schema' returns the field catalog + filterable/sortable lists, NO API call — use this first to discover available fields. One of: `items`, `count`, `schema`. |
</Accordion>

<Accordion title="marketing_auto_enrollments" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Who an automation has enrolled and what happened to each of them. Without contact_id: the enrollments list, newest first, one row per contact pass through the flow — the contact, status (active, completed, exited), the step they are on or ended at, when they enrolled and why they left; narrow with status, page with limit/offset, mode='count' for the total. The dashboard has no enrollments list either, so do not send the user to one.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | yes | The automation whose enrollments to read, from marketing_find_automations. |
| `contact_id` | string | no | Read this one contact's enrollments in the automation, each with its step-by-step trail, instead of the list. A contact id from marketing_find_contacts or from a row of this tool's list. |
| `status` | string | no | List only enrollments in this status. Ignored with contact_id. One of: `active`, `completed`, `exited`. |
| `fields` | array of string | no | Dot-path fields to return per row. Default: small preview (full row with contact_id). Use ['*'] for the full row. **Call mode='schema' first to discover valid paths before guessing.** |
| `limit` | integer | no | Page size, default 25, max 200. Ignored with contact_id. |
| `offset` | integer | no | Pagination offset. Use next_offset from the previous response. Ignored with contact_id. |
| `mode` | string | no | 'items' (default) returns rows. 'count' returns \{total\}. 'schema' returns the field catalog, NO API call. One of: `items`, `count`, `schema`. |
</Accordion>

<Accordion title="marketing_create_automation" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Creates an automation in inactive status. STRONGLY RECOMMENDED: call marketing_automation_library first and clone a starter (welcome-series, order-confirmation, win-back, birthday-greeting, renewal-reminder). Each step needs a unique local_id for cross-step references; the schema enforces local_id uniqueness and that yes_/no_next_step_local_id / parent_condition_local_id point at existing steps. Full step shape is in ms-marketing AutomationDocs.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `name` | string | yes | Unique per site — server enforces (brand_id, name) uniqueness. |
| `trigger_type` | string | yes | What starts this automation. One of: `contact_created`, `tag_added`, `tag_removed`, `form_submitted`, `order_created`, `cart_abandoned`, `booking_created`, `member_created`, `contact_field_changed`, `campaign_opened`, `campaign_clicked`, `contact_subscribed`, `blog_post_published`, `date_reached`. |
| `trigger_conditions` | object | no | Trigger-specific filters — flat key/value map, matched against the event payload by exact string equality; ALL keys must match or the trigger never fires (silently — no error). |
| `recipient_type` | string | no | Defaults to 'trigger' on the server when trigger_type is set. One of: `all`, `individual`, `date_range`, `segment`, `trigger`. |
| `segment_id` | string | no | Required when recipient_type is 'segment'. |
| `recipient_ids` | array of string | no | Required when recipient_type is 'individual'. |
| `recipient_filter` | object | no |   |
| `goal_type` | string | no | The automation's exit condition: what, if met, takes a contact out of the flow from wherever they have reached. One of 'tag_added', 'tag_removed', 'field_equals', 'active_again'. |
| `goal_conditions` | object | no | What goal_type compares, keyed by that type. |
| `steps` | array of object | no | Ordered steps to create alongside the automation. |
| `steps[].local_id` | string | yes | Stable string id used for cross-step references (e.g. CONDITION branches naming next steps by local_id). |
| `steps[].step_type` | string | yes | send_email, send_sms, wait, wait_until, condition, exit, add_tag, remove_tag, or update_field. Full per-type field requirements are in ms-marketing AutomationDocs.STEP_TYPE_GUIDE. One of: `send_email`, `send_sms`, `wait`, `wait_until`, `condition`, `exit`, `add_tag`, `remove_tag`, `update_field`. |
| `steps[].name` | string | no |   |
| `steps[].position` | integer | no |   |
| `steps[].branch` | string | no | 'yes' or 'no' for children of a condition step. One of: `yes`, `no`. |
| `steps[].parent_condition_local_id` | string | no |   |
| `steps[].subject` | string | no |   |
| `steps[].preview_text` | string | no | send_email: the line an inbox prints after the subject, and the server applies it — it is rendered and injected as the email's preheader on send. Optional; left unset, the inbox falls back to the email's own opening text. |
| `steps[].email_json` | object | no | Structured email content as a block graph. Map&lt;String, Block&gt;. |
| `steps[].archetype` | string | no | send_email step: the marketing_email_recipe archetype (starter id) this email was composed from. Not stored — it lets the design check judge the email against that composition. |
| `steps[].from_template` | string | no | Build this email from a designed template, keeping its layout EXACTLY: pass the library template id from marketing_email_recipe together with slots, and leave email_json out. |
| `steps[].slots` | object | no | The copy to write into the template, keyed by block id: \{ "&lt;block_id&gt;": \{ text \| url \| alt \| links \| backgroundImage \} \}. marketing_email_recipe lists every slot with the sample copy it currently holds. |
| `steps[].sender` | object | no | send_email step: who the mail comes from. |
| `steps[].body` | string | no |   |
| `steps[].wait_duration` | integer | no | wait step: how long to wait. wait_until step: the optional timeout after which the enrollment moves on whether or not the condition was met — 0 or omitted there means no timeout at all and the wait runs until its condition is met. |
| `steps[].wait_unit` | string | no | The unit of wait_duration on a wait or wait_until step: 'minutes', 'hours', 'days' or 'weeks', matched exactly — a spelling outside those four is a 400, and so are 'Days' and ' days '. One of: `minutes`, `hours`, `days`, `weeks`. |
| `steps[].wait_until_date` | string | no | wait_until step, condition_type='date_reached': the one absolute instant every contact waits for, RFC 3339 (e.g. "2026-12-24T09:00:00Z"). No offset means UTC. Required for that condition type — with none the wait never releases. |
| `steps[].date_field_key` | string | no | wait_until step, condition_type='date_relative': which of the contact's dates the wait resolves against — the key of a DATE custom field (from marketing_list_custom_fields), the literal 'created_at' for the signup date, the literal 'last_order_date' for the customer's last order placed date (date_recurrence 'exact' only — a new order moves it — and only on a site offered the commerce fields), or 'contact.last_activity' for the day of the contact's last form, booking, order, abandoned cart or member signup (it reads the contact's last_contacted_at, the field marketing_find_contacts returns; it takes date_recurrence 'exact' and a date_offset_days of 0 or more; a contact with no activity stays held until the step's timeout, if it has one). |
| `steps[].date_offset_days` | integer | no | wait_until step, condition_type='date_relative': signed whole days to shift the date by. -7 releases a week before it, 3 three days after, 0 (the default when omitted) on the day itself. |
| `steps[].date_recurrence` | string | no | wait_until step, condition_type='date_relative': 'annual' for a date that comes round every year (a birthday, a work anniversary) — the wait releases on the next occurrence on or after the day the contact entered it; 'exact' for a date that happens once (a renewal, an appointment). One of: `exact`, `annual`. |
| `steps[].condition_type` | string | no | condition step: 'opened' and 'clicked' wait for engagement with the most recent send_email of the enrollment and take condition_check_after + condition_check_unit as the wait. One of: `opened`, `clicked`, `has_tags`, `belongs_to_segment`, `field_comparison`, `tag_added`, `tag_removed`, `field_equals`, `date_reached`, `date_relative`. |
| `steps[].condition_check_after` | integer | no | condition step, condition_type 'opened' or 'clicked': how long to wait for that engagement before giving up and taking the NO branch. |
| `steps[].condition_check_unit` | string | no | The unit of condition_check_after: 'minutes', 'hours' or 'days', matched exactly. |
| `steps[].condition_operator` | string | no | condition step, for the two condition types that need one — and, optionally, a wait_until step with condition_type 'field_equals' (see the end). has_tags — how tag_names is matched: 'all' (every tag listed; the default when this field is omitted) or 'any' (at least one of them). field_comparison — how field_key is compared to field_value; which operators apply depends on the field's type, and one outside its list is rejected: text columns and TEXT/LONG_TEXT/URL/EMAIL/PHONE fields take equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty; NUMBER fields and the two order amounts (total_order_amount, last_order_amount) take equals, not_equals, greater_than, less_than, greater_or_equal, less_or_equal — an order amount the contact does not have yet compares as 0, so less_than 10 matches a contact who never ordered; DATE fields, the date columns (created_at, updated_at, last_contacted_at, next_follow_up_at) and last_order_date take before, after, on, equals, each with a YYYY-MM-DD field_value compared in UTC, and a contact with no last_order_date matches none of them; BOOLEAN fields take equals; lifecycle_stage, lead_source, status and DROPDOWN/SINGLE_SELECT fields take equals, not_equals, is_empty, is_not_empty; MULTI_SELECT fields take contains, not_contains, is_empty, is_not_empty. is_empty and is_not_empty take no field_value. |
| `steps[].condition_segment_uuid` | string | no | condition step, condition_type=belongs_to_segment: the id of the segment whose membership decides the branch, from marketing_find_segments. |
| `steps[].yes_next_step_local_id` | string | no |   |
| `steps[].no_next_step_local_id` | string | no |   |
| `steps[].end_status` | string | no | exit steps only: what reaching this end means for the contact — 'exited' or 'completed'. One of: `exited`, `completed`. |
| `steps[].tag_names` | array of string | no | add_tag / remove_tag: the tags to apply, in order. The step applies every tag it lists and reports each one separately, so a tag_added/tag_removed trigger still fires per tag. |
| `steps[].tag_name` | string | no | DEPRECATED — use tag_names. add_tag / remove_tag: a single tag. Accepted as a one-tag list. Sending it alongside a tag_names whose first entry differs is rejected by the server. |
| `steps[].field_key` | string | no |   |
| `steps[].field_value` | string | no |   |
</Accordion>

<Accordion title="marketing_update_automation" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Updates an automation envelope (PATCH semantics) — name, trigger, recipients, goal, schedule. Editing an active automation requires pausing first (server-side rule). This endpoint does NOT manage steps; to change the step graph use the per-step tools: marketing_auto_add_step, marketing_auto_update_step (e.g. to edit a step's email content), marketing_auto_delete_step, and marketing_auto_reorder_steps. (`steps` passed here is ignored.)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | yes | Automation id from marketing_find_automations — always fetch first; never guess or reuse ids from earlier conversations. |
| `name` | string | no |   |
| `trigger_type` | string | no | What starts this automation. One of: `contact_created`, `tag_added`, `tag_removed`, `form_submitted`, `order_created`, `cart_abandoned`, `booking_created`, `member_created`, `contact_field_changed`, `campaign_opened`, `campaign_clicked`, `contact_subscribed`, `blog_post_published`, `date_reached`. |
| `trigger_conditions` | object | no | Trigger-specific filters — flat key/value map, matched against the event payload by exact string equality; ALL keys must match or the trigger never fires (silently — no error). |
| `recipient_type` | string | no | One of: `all`, `individual`, `date_range`, `segment`, `trigger`. |
| `segment_id` | string | no |   |
| `recipient_ids` | array of string | no |   |
| `recipient_filter` | object | no |   |
| `goal_type` | string | no | The automation's exit condition: what, if met, takes a contact out of the flow from wherever they have reached. One of 'tag_added', 'tag_removed', 'field_equals', 'active_again'. |
| `goal_conditions` | object | no | What goal_type compares, keyed by that type. |
</Accordion>

<Accordion title="marketing_delete_automation" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Deletes an automation. DESTRUCTIVE — any in-flight enrolled contacts will stop receiving steps. An active automation cannot be deleted; pause it first (marketing_set_automation_state status="paused") — server-side rule, same as editing. Set confirm_name to the automation's exact name; the tool fetches the automation and errors if they disagree.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | yes | Automation id from marketing_find_automations — always fetch first; never guess or reuse ids from earlier conversations. |
| `confirm_name` | string | yes | Must equal the automation's exact name — a guard against deleting the wrong automation. |
</Accordion>

<Accordion title="marketing_set_automation_state" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Activates or pauses an automation. status="active" starts real sends for matching events (route: /activate); "paused" stops new enrollment and halts in-flight progression (route: /deactivate).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | yes | Automation id from marketing_find_automations — always fetch first; never guess or reuse ids from earlier conversations. |
| `status` | string | yes | One of: `active`, `paused`. |
</Accordion>

<Accordion title="marketing_set_auto_archived" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Archives an automation or restores it. archived=true takes it off the live list without changing its status or stopping anything already enrolled (route: /archive); archived=false puts it back (route: /restore). An active automation cannot be archived — pause it first with marketing_set_automation_state — and an archived one cannot be activated until it is restored. Archiving is not deleting and it is reversible: marketing_delete_automation archives implicitly and then destroys the automation, its steps, its enrollments and its logs. Prefer this when the user wants an automation out of the way.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | yes | Automation id from marketing_find_automations — always fetch first; never guess or reuse ids from earlier conversations. |
| `archived` | boolean | yes | true archives the automation, false restores it. |
</Accordion>

<Accordion title="marketing_automation_library" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Returns the curated library of starter automations: welcome-series, order-confirmation, win-back, birthday-greeting and renewal-reminder. Use this as the starting point for marketing_create_automation — clone a starter and customize rather than building the step graph from scratch. The last two are the worked examples of a date_reached trigger, birthday-greeting on an annual date and renewal-reminder seven days before an exact one; clone whichever is closer rather than assembling the parameter map by hand.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
</Accordion>

<Accordion title="marketing_auto_add_step" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Adds a single step to an EXISTING automation — fully supported; use it to append/insert a step (e.g. a follow-up send_email, a wait, or a condition) without recreating the automation, and never say modifying an existing automation is unsupported.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | yes | Automation id from marketing_find_automations — always fetch first; never guess or reuse ids from earlier conversations. |
| `step_type` | string | yes | send_email, send_sms, wait, wait_until, condition, exit, add_tag, remove_tag, or update_field. Full per-type field requirements are in ms-marketing AutomationDocs.STEP_TYPE_GUIDE. One of: `send_email`, `send_sms`, `wait`, `wait_until`, `condition`, `exit`, `add_tag`, `remove_tag`, `update_field`. |
| `name` | string | no |   |
| `position` | integer | no | 0-based insert position; appended to the end when omitted. Existing steps at/after it shift down. |
| `branch` | string | no | 'yes' or 'no' when this step is a child of a condition step. One of: `yes`, `no`. |
| `parent_condition_id` | string | no | UUID of an existing parent condition step (when this step is a branch child). |
| `subject` | string | no |   |
| `preview_text` | string | no | send_email: the line an inbox prints after the subject, and the server applies it — it is rendered and injected as the email's preheader on send. Optional; left unset, the inbox falls back to the email's own opening text. |
| `email_json` | object | no | Structured email content as a block graph. Map&lt;String, Block&gt;. |
| `archetype` | string | no | send_email step: the marketing_email_recipe archetype (starter id) this email was composed from. Not stored — it lets the design check judge the email against that composition. |
| `from_template` | string | no | Build this email from a designed template, keeping its layout EXACTLY: pass the library template id from marketing_email_recipe together with slots, and leave email_json out. |
| `slots` | object | no | The copy to write into the template, keyed by block id: \{ "&lt;block_id&gt;": \{ text \| url \| alt \| links \| backgroundImage \} \}. marketing_email_recipe lists every slot with the sample copy it currently holds. |
| `sender` | object | no | send_email step: who the mail comes from. |
| `body` | string | no |   |
| `wait_duration` | integer | no | wait step: how long to wait. wait_until step: the optional timeout after which the enrollment moves on whether or not the condition was met — 0 or omitted there means no timeout at all and the wait runs until its condition is met. |
| `wait_unit` | string | no | The unit of wait_duration on a wait or wait_until step: 'minutes', 'hours', 'days' or 'weeks', matched exactly — a spelling outside those four is a 400, and so are 'Days' and ' days '. One of: `minutes`, `hours`, `days`, `weeks`. |
| `wait_until_date` | string | no | wait_until step, condition_type='date_reached': the one absolute instant every contact waits for, RFC 3339 (e.g. "2026-12-24T09:00:00Z"). No offset means UTC. Required for that condition type — with none the wait never releases. |
| `date_field_key` | string | no | wait_until step, condition_type='date_relative': which of the contact's dates the wait resolves against — the key of a DATE custom field (from marketing_list_custom_fields), the literal 'created_at' for the signup date, the literal 'last_order_date' for the customer's last order placed date (date_recurrence 'exact' only — a new order moves it — and only on a site offered the commerce fields), or 'contact.last_activity' for the day of the contact's last form, booking, order, abandoned cart or member signup (it reads the contact's last_contacted_at, the field marketing_find_contacts returns; it takes date_recurrence 'exact' and a date_offset_days of 0 or more; a contact with no activity stays held until the step's timeout, if it has one). |
| `date_offset_days` | integer | no | wait_until step, condition_type='date_relative': signed whole days to shift the date by. -7 releases a week before it, 3 three days after, 0 (the default when omitted) on the day itself. |
| `date_recurrence` | string | no | wait_until step, condition_type='date_relative': 'annual' for a date that comes round every year (a birthday, a work anniversary) — the wait releases on the next occurrence on or after the day the contact entered it; 'exact' for a date that happens once (a renewal, an appointment). One of: `exact`, `annual`. |
| `condition_type` | string | no | condition step: 'opened' and 'clicked' wait for engagement with the most recent send_email of the enrollment and take condition_check_after + condition_check_unit as the wait. One of: `opened`, `clicked`, `has_tags`, `belongs_to_segment`, `field_comparison`, `tag_added`, `tag_removed`, `field_equals`, `date_reached`, `date_relative`. |
| `condition_check_after` | integer | no | condition step, condition_type 'opened' or 'clicked': how long to wait for that engagement before giving up and taking the NO branch. |
| `condition_check_unit` | string | no | The unit of condition_check_after: 'minutes', 'hours' or 'days', matched exactly. |
| `condition_operator` | string | no | condition step, for the two condition types that need one — and, optionally, a wait_until step with condition_type 'field_equals' (see the end). has_tags — how tag_names is matched: 'all' (every tag listed; the default when this field is omitted) or 'any' (at least one of them). field_comparison — how field_key is compared to field_value; which operators apply depends on the field's type, and one outside its list is rejected: text columns and TEXT/LONG_TEXT/URL/EMAIL/PHONE fields take equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty; NUMBER fields and the two order amounts (total_order_amount, last_order_amount) take equals, not_equals, greater_than, less_than, greater_or_equal, less_or_equal — an order amount the contact does not have yet compares as 0, so less_than 10 matches a contact who never ordered; DATE fields, the date columns (created_at, updated_at, last_contacted_at, next_follow_up_at) and last_order_date take before, after, on, equals, each with a YYYY-MM-DD field_value compared in UTC, and a contact with no last_order_date matches none of them; BOOLEAN fields take equals; lifecycle_stage, lead_source, status and DROPDOWN/SINGLE_SELECT fields take equals, not_equals, is_empty, is_not_empty; MULTI_SELECT fields take contains, not_contains, is_empty, is_not_empty. is_empty and is_not_empty take no field_value. |
| `condition_segment_uuid` | string | no | condition step, condition_type=belongs_to_segment: the id of the segment whose membership decides the branch, from marketing_find_segments. |
| `yes_next_step_id` | string | no | UUID of an existing step to run on the YES branch. |
| `no_next_step_id` | string | no | UUID of an existing step to run on the NO branch. |
| `end_status` | string | no | exit steps only: what reaching this end means for the contact — 'exited' or 'completed'. One of: `exited`, `completed`. |
| `tag_names` | array of string | no | add_tag / remove_tag: the tags to apply, in order. The step applies every tag it lists and reports each one separately, so a tag_added/tag_removed trigger still fires per tag. |
| `tag_name` | string | no | DEPRECATED — use tag_names. add_tag / remove_tag: a single tag. Accepted as a one-tag list. Sending it alongside a tag_names whose first entry differs is rejected by the server. |
| `field_key` | string | no |   |
| `field_value` | string | no |   |
| `yes_next_step_local_id` | string | no |   |
| `no_next_step_local_id` | string | no |   |
| `parent_condition_local_id` | string | no |   |
</Accordion>

<Accordion title="marketing_auto_update_step" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Edits a step IN AN EXISTING AUTOMATION in place — fully supported; NEVER tell the user that editing an automation's email content/steps is unsupported or that they must use the dashboard builder. PATCH semantics: omitted fields are left unchanged. The common use is editing a step's EMAIL CONTENT — read the step's current email_json (marketing_find_automations with fields=['*']), modify the block graph, and pass the WHOLE modified email_json (and/or subject) here. step_type is immutable; to change a step's type, delete it and add a new one. Position is changed via marketing_auto_reorder_steps.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | yes | Automation id from marketing_find_automations — always fetch first; never guess or reuse ids from earlier conversations. |
| `step_id` | string | yes | UUID of the step to update. |
| `name` | string | no |   |
| `branch` | string | no | 'yes' or 'no' when this step is a child of a condition step. One of: `yes`, `no`. |
| `parent_condition_id` | string | no | UUID of an existing parent condition step (when this step is a branch child). |
| `subject` | string | no |   |
| `preview_text` | string | no | send_email: the line an inbox prints after the subject, and the server applies it — it is rendered and injected as the email's preheader on send. Optional; left unset, the inbox falls back to the email's own opening text. |
| `email_json` | object | no | Structured email content as a block graph. Map&lt;String, Block&gt;. |
| `archetype` | string | no | send_email step: the marketing_email_recipe archetype (starter id) this email was composed from. Not stored — it lets the design check judge the email against that composition. |
| `from_template` | string | no | Build this email from a designed template, keeping its layout EXACTLY: pass the library template id from marketing_email_recipe together with slots, and leave email_json out. |
| `slots` | object | no | The copy to write into the template, keyed by block id: \{ "&lt;block_id&gt;": \{ text \| url \| alt \| links \| backgroundImage \} \}. marketing_email_recipe lists every slot with the sample copy it currently holds. |
| `sender` | object | no | send_email step: who the mail comes from. |
| `body` | string | no |   |
| `wait_duration` | integer | no | wait step: how long to wait. wait_until step: the optional timeout after which the enrollment moves on whether or not the condition was met — 0 or omitted there means no timeout at all and the wait runs until its condition is met. |
| `wait_unit` | string | no | The unit of wait_duration on a wait or wait_until step: 'minutes', 'hours', 'days' or 'weeks', matched exactly — a spelling outside those four is a 400, and so are 'Days' and ' days '. One of: `minutes`, `hours`, `days`, `weeks`. |
| `wait_until_date` | string | no | wait_until step, condition_type='date_reached': the one absolute instant every contact waits for, RFC 3339 (e.g. "2026-12-24T09:00:00Z"). No offset means UTC. Required for that condition type — with none the wait never releases. |
| `date_field_key` | string | no | wait_until step, condition_type='date_relative': which of the contact's dates the wait resolves against — the key of a DATE custom field (from marketing_list_custom_fields), the literal 'created_at' for the signup date, the literal 'last_order_date' for the customer's last order placed date (date_recurrence 'exact' only — a new order moves it — and only on a site offered the commerce fields), or 'contact.last_activity' for the day of the contact's last form, booking, order, abandoned cart or member signup (it reads the contact's last_contacted_at, the field marketing_find_contacts returns; it takes date_recurrence 'exact' and a date_offset_days of 0 or more; a contact with no activity stays held until the step's timeout, if it has one). |
| `date_offset_days` | integer | no | wait_until step, condition_type='date_relative': signed whole days to shift the date by. -7 releases a week before it, 3 three days after, 0 (the default when omitted) on the day itself. |
| `date_recurrence` | string | no | wait_until step, condition_type='date_relative': 'annual' for a date that comes round every year (a birthday, a work anniversary) — the wait releases on the next occurrence on or after the day the contact entered it; 'exact' for a date that happens once (a renewal, an appointment). One of: `exact`, `annual`. |
| `condition_type` | string | no | condition step: 'opened' and 'clicked' wait for engagement with the most recent send_email of the enrollment and take condition_check_after + condition_check_unit as the wait. One of: `opened`, `clicked`, `has_tags`, `belongs_to_segment`, `field_comparison`, `tag_added`, `tag_removed`, `field_equals`, `date_reached`, `date_relative`. |
| `condition_check_after` | integer | no | condition step, condition_type 'opened' or 'clicked': how long to wait for that engagement before giving up and taking the NO branch. |
| `condition_check_unit` | string | no | The unit of condition_check_after: 'minutes', 'hours' or 'days', matched exactly. |
| `condition_operator` | string | no | condition step, for the two condition types that need one — and, optionally, a wait_until step with condition_type 'field_equals' (see the end). has_tags — how tag_names is matched: 'all' (every tag listed; the default when this field is omitted) or 'any' (at least one of them). field_comparison — how field_key is compared to field_value; which operators apply depends on the field's type, and one outside its list is rejected: text columns and TEXT/LONG_TEXT/URL/EMAIL/PHONE fields take equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty; NUMBER fields and the two order amounts (total_order_amount, last_order_amount) take equals, not_equals, greater_than, less_than, greater_or_equal, less_or_equal — an order amount the contact does not have yet compares as 0, so less_than 10 matches a contact who never ordered; DATE fields, the date columns (created_at, updated_at, last_contacted_at, next_follow_up_at) and last_order_date take before, after, on, equals, each with a YYYY-MM-DD field_value compared in UTC, and a contact with no last_order_date matches none of them; BOOLEAN fields take equals; lifecycle_stage, lead_source, status and DROPDOWN/SINGLE_SELECT fields take equals, not_equals, is_empty, is_not_empty; MULTI_SELECT fields take contains, not_contains, is_empty, is_not_empty. is_empty and is_not_empty take no field_value. |
| `condition_segment_uuid` | string | no | condition step, condition_type=belongs_to_segment: the id of the segment whose membership decides the branch, from marketing_find_segments. |
| `yes_next_step_id` | string | no | UUID of an existing step to run on the YES branch. |
| `no_next_step_id` | string | no | UUID of an existing step to run on the NO branch. |
| `end_status` | string | no | exit steps only: what reaching this end means for the contact — 'exited' or 'completed'. One of: `exited`, `completed`. |
| `tag_names` | array of string | no | add_tag / remove_tag: the tags to apply, in order. The step applies every tag it lists and reports each one separately, so a tag_added/tag_removed trigger still fires per tag. |
| `tag_name` | string | no | DEPRECATED — use tag_names. add_tag / remove_tag: a single tag. Accepted as a one-tag list. Sending it alongside a tag_names whose first entry differs is rejected by the server. |
| `field_key` | string | no |   |
| `field_value` | string | no |   |
| `yes_next_step_local_id` | string | no |   |
| `no_next_step_local_id` | string | no |   |
| `parent_condition_local_id` | string | no |   |
</Accordion>

<Accordion title="marketing_auto_delete_step" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Deletes a single step from an automation. DESTRUCTIVE — deleting a condition deletes every step inside its yes/no branches too, recursively. Branch references at any deleted step are cleared server-side, so the graph is left consistent; re-point them with marketing_auto_update_step if the flow should continue past the gap. Refused on an active automation (pause it first) and, on a scheduled one, when the delete would take the last send_email or send_sms step with it — add another message step first, then delete this one.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | yes | Automation id from marketing_find_automations — always fetch first; never guess or reuse ids from earlier conversations. |
| `step_id` | string | yes | UUID of the step to delete. |
</Accordion>

<Accordion title="marketing_auto_reorder_steps" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Reorders an automation's steps. step_ids must be the EXACT full set of the automation's current step UUIDs (every step exactly once) in the desired order — the server rejects a partial, duplicate, or foreign id set. Get the current ids from marketing_find_automations with automation_id and fields=['*']. An order may put a step below an exit — that ends the flow at the exit and the steps after it stop running, which is the author's to choose.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `automation_id` | string | yes | Automation id from marketing_find_automations — always fetch first; never guess or reuse ids from earlier conversations. |
| `step_ids` | array of string | yes | Exact full set of the automation's step UUIDs, in the new order. |
</Accordion>

<Accordion title="marketing_list_variables" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Lists the merge variables usable in email/SMS subject and body for this site. Call with NO trigger_type for campaigns or non-event automations — returns the always-available "global" variables plus a "custom_fields" pointer. Pass trigger_type for an event-triggered automation to additionally get that trigger's "event" variables (with labels and example values). This is the authoritative source — call it before writing \{\{event.*\}\} or \{\{custom.*\}\} tokens into content. "event.lists" entries are repeatable arrays: replace N in token_pattern with a 0-based index (e.g. \{\{event.items.0.name\}\}).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `trigger_type` | string | no | Event trigger type. Omit for campaigns / non-event automations. Pass to add that trigger's \{\{event.*\}\} variables. One of the MarketingEventType values. One of: `contact_created`, `tag_added`, `tag_removed`, `form_submitted`, `order_created`, `cart_abandoned`, `booking_created`, `member_created`, `contact_field_changed`, `campaign_opened`, `campaign_clicked`, `contact_subscribed`, `blog_post_published`, `date_reached`. |
</Accordion>

<Accordion title="marketing_link_targets" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

The ONLY source of URLs for links inside a marketing email (Button url, Image linkHref, markdown links, SocialIcons aside). Returns this site's pages, blog posts and store products, each with its live public_url (pages at https://&lt;domain&gt;/&lt;path&gt;, the home page at the bare domain; blog posts at https://&lt;domain&gt;/&lt;path&gt;; store products at https://&lt;domain&gt;/product/&lt;slug&gt;). Use public_url verbatim — never assemble a URL from a slug or a title, and never leave the starter's https://REPLACE_ME.example.com in place (the save is refused).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes |   |
| `kind` | string | no | Limit to one family. Omit for all three. One of: `pages`, `blog_posts`, `products`. |
| `search` | string | no | Case-insensitive substring of the page/post/product title. |
| `limit` | integer | no | Max targets returned (default 50). |
</Accordion>

<Accordion title="marketing_list_labels" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Lists the site's labels. A label is the site's definition of a contact tag — its name and its colour. Call this before creating one: names collide regardless of case, so "vip" is refused when "VIP" exists.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `offset` | integer | no |   |
| `limit` | integer | no |   |
</Accordion>

<Accordion title="marketing_create_label" icon="fa-pen-to-square">
**Plan:** Custom Plan · **Access:** Write (destructive)

Creates a label on its own, tagging nobody. Use this when the user wants a label defined up front — typically so an automation's add_tag step can apply it later. Do NOT tag contacts to bring a label into existence; that is a separate decision the user has to ask for. Tagging a contact does create the label too, so a tag never exists without one.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `name` | string | yes | The tag this label defines. Example: "VIP". |
| `color` | string | no | Omit unless the user asked for a specific colour — the server then picks the same colour the tag would have had. One of: `lilac`, `red`, `orange`, `light-green`, `dark-green`, `dark-blue`, `grey`, `purple`, `light-grey`, `flex-color`. |
</Accordion>

<Accordion title="marketing_get_limits" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Returns what the site's plan allows in marketing and how much of it the site has used. Call it when the user asks about their plan, their limits or how many emails they have left; before sending a campaign to a large audience; and when a send or an automation activation is refused for a limit, so you can say what was reached and when it resets.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
</Accordion>

<Accordion title="marketing_check_suggestions" icon="fa-eye">
**Plan:** Custom Plan · **Access:** Read-only

Checks a draft of the marketing Home suggestions (3 emails or none, 1 SMS, 1 automation) with the same rules the Home card applies, and returns \{ clean, email_problems, sms_problems, automation_problems \}; each problem names the item id and the field. Run it before returning Home suggestions; fix every problem it lists and call it again until clean is true. It saves nothing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique name of the site. |
| `business` | string | yes | One line on the business the suggestions are written for. |
| `emails` | array of object | yes | 3 suggested emails, or none when the site has nothing of its own to suggest from; the Home card shows 3. |
| `emails[].id` | string | yes | The suggestion id problems refer to. |
| `emails[].template_id` | string | yes | The library template id from marketing_email_recipe. |
| `emails[].title` | string | yes | Card title shown on Home. |
| `emails[].subtitle` | string | yes | Card subtitle shown on Home. |
| `emails[].subject` | string | yes | Email subject line. |
| `emails[].slots` | array of object | yes | The copy written into the template, one entry per block. |
| `sms` | object or null | yes | The suggested SMS, or null when there is none. |
| `sms.id` | string | yes | The suggestion id problems refer to. |
| `sms.title` | string | yes | Card title shown on Home. |
| `sms.description` | string | yes | Card description shown on Home. |
| `sms.message` | string | yes | The SMS text. |
| `automation` | object or null | yes | The suggested automation, or null when there is none. |
| `automation.id` | string | yes | The suggestion id problems refer to. |
| `automation.title` | string | yes | Card title shown on Home. |
| `automation.description` | string | yes | Card description shown on Home. |
| `automation.trigger` | string | yes | What starts the automation. |
| `automation.steps` | array of object | yes | The automation steps in order. |
| `automation.steps[].kind` | string | yes | An email step or a wait between steps. One of: `email`, `wait`. |
| `automation.steps[].id` | string | yes | The step id problems refer to. |
| `automation.steps[].label` | string | no | What the step does, as shown on Home. |
| `automation.steps[].template_id` | string | no | Email steps: the library template id from marketing_email_recipe. |
| `automation.steps[].subject` | string | no | Email steps: the subject line. |
| `automation.steps[].slots` | array of any | no | Email steps: the copy written into the template, one entry per block. |
</Accordion>

### Vibe

<Accordion title="vibe_list_files" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

List the source files of a Vibe-built site: each file's 'path' and 'size_bytes', without contents. Only the site's own source is listed (its pages, components and API handlers) — build config, lockfiles and settings are not exposed. Start here, then read the handful of files you actually need with vibe_read_files. Always reflects the site's current state.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target Vibe site (e.g. 'my-site-123'). |
| `path_prefixes` | array of string | no | Optional. Restrict the listing to files under any of these paths (e.g. ['client/src/blocks', 'server/api']). Useful on large sites to avoid pulling the whole tree. |
</Accordion>

<Accordion title="vibe_read_files" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Read the contents of specific files from a Vibe-built site. Pass every file you need in one call — up to 20 — rather than calling this once per file: each call re-reads the site's whole repository, so one batched call is far cheaper than several small ones. Paths come from vibe_list_files. A path that no longer exists is simply omitted from the response rather than failing the batch, and every file comes back whole — contents are never truncated.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target Vibe site (e.g. 'my-site-123'). |
| `paths` | array of string | yes | The files to read, as returned by vibe_list_files (e.g. ['client/src/App.tsx', 'server/api/lead.ts']). At most 20 per call. |
</Accordion>

<Accordion title="vibe_get_tables" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

List the tables of a Vibe-built site, or describe one when 'table_name' is given. Each table has its 'name', 'columns' with their types ('string', 'number', 'boolean', 'date', 'longstring', 'user'), foreign keys (a 'references' key such as 'customers.id', present only on foreign-key columns) and approximate row count ('total'). Start here to see what data a Vibe site stores, such as bookings, signups or products, and for a table's columns before reading its rows, which come without them. Reading never changes the site.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target Vibe site (e.g. 'my-site-123'). |
| `table_name` | string | no | Optional. Describe only this table; leave it out to list them all. |
</Accordion>

<Accordion title="vibe_query_rows" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Read the rows of a Vibe-built site's table in 'id' order: up to 'limit' rows (default 50, at most 100) starting at 'offset', returned in 'results'. For the next page use 'offset' plus 'limit', but at most 50,000; stop once 'offset' plus the rows returned reaches 'total', or after reading at offset 50,000, so only the first 50,100 rows can be read. Every call re-reads all the rows before 'offset', so deep pages are slow and costly: use limit 100 when reading many rows. Row keys are the table's column names, dates are UTC strings with no offset (e.g.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target Vibe site (e.g. 'my-site-123'). |
| `table_name` | string | yes | Table name as returned by vibe_get_tables. |
| `limit` | integer | no | Optional. Rows to return, 1-100; defaults to 50. |
| `offset` | integer | no | Optional. Rows to skip, 0-50000; defaults to 0. For the next page, add the previous call's limit. |
</Accordion>

<Accordion title="vibe_edit_tables" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Add tables or columns to a Vibe-built site. 'method' picks the change: - create_table: a new table 'table_name' (lowercase snake_case, e.g. 'order_items') with 'columns' (1-20). Every table also gets an 'id' column, numbered automatically. Returns the new table. - add_columns: add 'columns' to the table, all or none; existing rows get no value for them. A table has at most 20 columns besides 'id'. Returns the updated table. Writes change the live site's data immediately, and the site's code reads these tables, so call vibe_get_tables first to see the tables, their columns and types.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target Vibe site (e.g. 'my-site-123'). |
| `method` | string | yes | The change to make; see the tool description. One of: `create_table`, `add_columns`. |
| `table_name` | string | yes | The table to change, as returned by vibe_get_tables; for create_table, the new table's name. |
| `columns` | array of object | yes | The columns to add, 1-20, without 'id'. |
| `columns[].name` | string | yes | Column name, 1-64 letters, digits or '_'. 'id' is reserved: every table has it. |
| `columns[].type` | string | yes | 'string', 'number', 'boolean', 'date', 'longstring' (long text up to 64 KB, never indexed) or 'user' (a site member's auth user id). One of: `string`, `number`, `boolean`, `date`, `longstring`, `user`. |
| `columns[].references` | string | no | Optional. Makes this a foreign key to another table's rows, as '&lt;table&gt;.id' (e.g. 'customers.id'). The column must be type 'number'. |
</Accordion>

<Accordion title="vibe_edit_rows" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Insert, update or delete rows in a Vibe-built site's table. 'method' picks the change, and each method takes its own arguments: - insert: insert 'rows' (1-100). The whole batch is checked before anything is written, so one bad row writes nothing and the error message names it as [row N] (0-based). Returns the rows as stored, with their new 'id'. For more than 100 rows, call again. - update: change some 'fields' of the row 'row_id'. Only the fields given change; null clears a field. Returns the whole row. - delete: permanently delete the rows 'row_ids' (1-100).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target Vibe site (e.g. 'my-site-123'). |
| `method` | string | yes | The change to make; see the tool description. One of: `insert`, `update`, `delete`. |
| `table_name` | string | yes | The table to change, as returned by vibe_get_tables. |
| `rows` | array of object | no | insert: the rows, 1-100. A column left out has no value. Keys are column names exactly as vibe_get_tables lists them. Values: strings, numbers, booleans, dates as ISO-8601 (no offset means UTC, e.g. |
| `row_id` | integer | no | update: the row's 'id', as returned by vibe_query_rows. |
| `fields` | object | no | update: the columns to change and their new values; null clears one. Keys are column names exactly as vibe_get_tables lists them. Values: strings, numbers, booleans, dates as ISO-8601 (no offset means UTC, e.g. |
| `row_ids` | array of integer | no | delete: the 'id' of each row to delete, as returned by vibe_query_rows; 1-100. |
</Accordion>

### Conversations

<Accordion title="conversation_find" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Every conversation on the site, most recently active first. Each carries its 'id', 'state', the agent's own 'title' for it (absent until it finishes a first turn), 'created_at' and 'last_activity_at'. Use the title to pick the conversation you mean rather than guessing from the id. Give a 'conversation_id' to get that one row on its own — the same fields, without pulling the whole list. This never blocks, so it is also the cheap way to see whether a turn is running.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g. 'my-site-123'). The site must have a conversational agent; today that means a Vibe site. |
| `conversation_id` | string | no | Optional. One conversation's row instead of every one on the site. |
</Accordion>

<Accordion title="conversation_get_messages" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

The conversation log, oldest first. Items are 'message' (text from the user or the agent), 'file' (an attachment), 'interaction_request' (the agent asking something — answer it with conversation_send_message) and 'answer' (a request already answered). Keep each page's 'cursor' and pass it back to read the next page; an empty 'results' means you are at the end, and its 'cursor' is still the place to read newer items from later. Every page also carries the conversation's 'state'. Note 'limit' bounds the stored rows read, not the items returned, so a page can hold more items than the limit.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g. 'my-site-123'). The site must have a conversational agent; today that means a Vibe site. |
| `conversation_id` | string | yes | The conversation's id, as returned by conversation_find or conversation_send_message. |
| `cursor` | string | no | Optional. The 'cursor' of the previous page. Omit to read from the start of the conversation. |
| `limit` | integer | no | Optional. How many stored rows to read, 1-100 (default 50). |
</Accordion>

<Accordion title="conversation_send_message" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Send one thing to the site's AI agent, which starts a turn: the agent reads the site, changes it and reports back. Omit 'conversation_id' to open a new conversation — the id it returns is what you pass next time; continuing an existing one keeps the agent's context.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g. 'my-site-123'). The site must have a conversational agent; today that means a Vibe site. |
| `conversation_id` | string | no | Optional. The conversation to send to. Omit to open a new one; the response carries its 'conversation_id'. |
| `text` | string | no | What to tell the agent, e.g. 'Add a bookings page that stores reservations'. One message carries at most one text; give the full instruction here. |
| `file_urls` | array of string | no | Optional. Publicly reachable http/https URLs the agent should look at (images, documents). The agent fetches them itself, so a private or signed-expired URL fails the turn. |
| `approved` | boolean | no | Only when the conversation is 'waiting_for_answer' on an 'approval' or 'credential' request: true to let the agent proceed, false to refuse. |
| `answers` | array of object | no | Only when the conversation is 'waiting_for_answer' on a 'question' request: one entry per question in the request's payload. |
| `answers[].question_id` | string | yes | The question's id, from the request's payload. |
| `answers[].selected_label` | string | no | The label of the single option chosen, copied verbatim from the request's payload. |
| `answers[].selected_labels` | array of string | no | For a question that allows several choices: the labels chosen, copied verbatim. |
| `answers[].other_text` | string | no | A free-text answer, when none of the offered options fits. |
| `answers[].skipped` | boolean | no | Set true to decline this question and let the agent decide for itself. |
</Accordion>

<Accordion title="conversation_wait" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Where the conversation stands and what has happened since your 'cursor'. This is the only tool that waits: it blocks until the turn stops, then reports the state it ended in — 'idle' when the agent finished, or 'waiting_for_answer' with the 'interaction_request' to answer. It returns at once when nothing is running, so it costs nothing to call on a finished conversation. A turn runs tens of seconds to a few minutes; if it outlives the wait the state comes back as 'in_progress' and you call again with the 'cursor' from the result. For state alone without ever blocking, use conversation_find.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g. 'my-site-123'). The site must have a conversational agent; today that means a Vibe site. |
| `conversation_id` | string | yes | The conversation's id, as returned by conversation_find or conversation_send_message. |
| `cursor` | string | no | Optional. The 'cursor' from conversation_send_message or from the previous result, to get 'new_items' — everything that has happened since. |
</Accordion>

<Accordion title="conversation_cancel" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Stop whatever the agent is currently doing in this conversation. Cancellation is eventual: the call returns at once but the turn takes a moment to wind down, so call conversation_wait, which waits for it to land on 'idle'. Work the agent already wrote to the site stays — this stops it going further, it does not undo it. Cancelling an idle conversation does nothing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | The unique identifier of the target site (e.g. 'my-site-123'). The site must have a conversational agent; today that means a Vibe site. |
| `conversation_id` | string | yes | The conversation's id, as returned by conversation_find or conversation_send_message. |
</Accordion>

### Elements

<Accordion title="get_element_schema" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Schema and rules for Duda page elements. No arguments: every element type with a one-line purpose plus the editing rules — call once before your first insert or update. With element_type (one or up to 10): the JSON Schema of its props (data, style, bindings), a minimal example and the type's rules. No API call.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `element_type` | string or array of string | no | One element type or up to 10 (e.g. ['SECTION','COLUMN','PARAGRAPH']). Omit for the summary of all types. One of: `ACCORDION`, `ADD_TO_CART`, `ADVANCED_ACCORDION`, `ADVANCED_ACCORDION_ITEM`, `ADVANCED_GRID`, `ADVANCED_TABS`, `ADVANCED_TABS_ITEM`, `BLOG_LIST`, `BLOG_SEARCH`, `BUTTON`, `CART`, `CHOICE`, `CLICK_TO_CALL`, `COLLECTION_SEARCH`, `COLUMN`, `CUSTOM_WIDGET`, `DATE_INPUT`, `DIVIDER`, `DROPDOWN`, `EMAIL`, `FILE_UPLOAD`, `FILTER_SORT`, `FOOTER`, `FORM_BUTTON`, `FORM_BUTTONS_CONTAINER`, `FORM_ELEMENT`, `FORM_STEP`, `HAMBURGER_BUTTON`, `HAMBURGER_MENU`, `HEADER`, `HTML`, `ICON`, `IMAGE`, `INNER_COLUMN`, `MAP`, `MEDIA_SLIDER`, `NAVIGATION`, `OPTIONS_VARIATIONS`, `OPT_IN`, `PARAGRAPH`, `PHOTO_GALLERY`, `PRODUCT_CUSTOMIZATIONS`, `PRODUCT_PRICE`, `PRODUCT_PRICE_OPTIONS`, `SECTION`, `SHAPE`, `SOCIAL_ICONS`, `SPACER`, `TABLE`, `TEXT_INPUT`, `UNKNOWN`, `VIDEO`. |
| `detail` | string | no | Which part to return. 'props' (default) = the JSON Schema for data + style + connected_data, with example and rules; 'data' / 'style' = that half alone; 'full' = 'props' with the API's field descriptions kept. One of: `props`, `data`, `style`, `example`, `full`. |
</Accordion>

<Accordion title="get_binding_options" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

List the site data an element can be bound to: Content Library business fields and the site's collections, each with its field keys, value types and current values. Call this before setting connected_data — copy `source` and `field` verbatim from a result. Field keys are not guessable from the raw content library: a phone labelled 'Studio' is `location_data.phones.studio`. Pass page_uuid on a dynamic page to include that page's item fields.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | Site name (e.g. 'a1b2c3d4'), from list_sites. |
| `page_uuid` | string | no | Include bindings available on this page, such as a dynamic page's own item fields. Omit for site-wide sources only. |
| `dynamic_page_item` | string | no | Resolve a dynamic page against this collection row id, so resolved_value shows real content. Requires page_uuid. |
</Accordion>

<Accordion title="search_site_text" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Find text anywhere on a site — every page plus the header and footer, page titles and SEO copy, and the navigation labels — in one call. Returns the matching elements with their page, id, type and a snippet — feed those ids to update_elements to change them. Pass several queries at once to cover other wordings and languages. Case-insensitive. Use this before a site-wide wording, price or contact-detail change so nothing is missed.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | Site name (e.g. 'a1b2c3d4'), from list_sites. |
| `query` | string or array of string | yes | Text to find, or up to 10 alternatives searched together — e.g. ['3 nights','3 Nächte','pay 2'] to catch a translated or reworded copy of the same thing. Matched case-insensitively against visible text, with HTML tags ignored. |
| `page_uuid` | string | no | Search only this page instead of the whole site. Header and footer are always included unless include_header_footer is false. |
| `include_header_footer` | boolean | no | Search the site header and footer, and the navigation labels, too. Default true. |
| `include_values` | boolean | no | Return the full current text of each matched field alongside the snippet, so a wording change needs no second read. Write it back with update_elements `set` at the same `field` path. |
| `max_pages` | integer | no | Cap on pages searched, default 25. The result says whether any were skipped. |
</Accordion>

<Accordion title="get_page_elements" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Read the element tree of a page, header or footer. Default is a compact outline: element_id, element_type, name, a one-line summary and children — enough to find what to edit. Add fields (e.g. ['props.data'], ['props.style.background'], ['*']) for props, or element_id + depth for one subtree. Flex sites only.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | Site name (e.g. 'a1b2c3d4'), from list_sites. |
| `target` | string | no | Which element tree: 'page' (default, needs page_uuid), the site 'header', or the site 'footer'. One of: `page`, `header`, `footer`. |
| `page_uuid` | string | no | Page UUID from list_pages. Required when target is 'page'; ignored otherwise. |
| `element_id` | string | no | Return only this element and its descendants. |
| `depth` | integer | no | Levels of children below the root(s). 0 = the node(s) only. Default: unlimited. |
| `fields` | array of string | no | Extra dot-paths per node besides the outline keys, e.g. ['props.data','props.style.spacing']. ['*'] = everything. A path from search_site_text works as-is; an indexed one like 'props.data.images[2].alt' projects under the key 'images[2]'. |
</Accordion>

<Accordion title="insert_elements" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Insert new elements into a page, header or footer. Each item needs element_type, parent_id and props; nest children to build a whole section (SECTION → COLUMN → widgets) in one call. Get shapes from get_element_schema first. Image src accepts a URL, a stock-photo phrase, or pexels://?query=…. dry_run validates without writing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | Site name (e.g. 'a1b2c3d4'), from list_sites. |
| `target` | string | no | Which element tree: 'page' (default, needs page_uuid), the site 'header', or the site 'footer'. One of: `page`, `header`, `footer`. |
| `page_uuid` | string | no | Page UUID from list_pages. Required when target is 'page'; ignored otherwise. |
| `elements` | array of object | yes | Top-level items to insert, in order. |
| `elements[].ref` | string | no | Your own label, echoed in results so you can map ids (e.g. 'hero'). |
| `elements[].element_type` | string | yes | e.g. SECTION, COLUMN, PARAGRAPH, BUTTON, IMAGE, TEXT_INPUT. See get_element_schema. |
| `elements[].parent_id` | string | no | Existing container id. Top-level items only: 'body' for a new section on a page, 'header'/'footer'/'hamburger_menu' on those targets. Children inherit their parent. |
| `elements[].next_sibling_id` | string | no | Insert before this sibling; omit to append. |
| `elements[].name` | string | no |   |
| `elements[].props` | object | no | \{data, style\} per get_element_schema(element_type). |
| `elements[].custom_class_names` | array of string | no |   |
| `elements[].connected_data` | object | no |   |
| `elements[].children` | array of any | no | Nested elements to create inside this one. |
| `dry_run` | boolean | no | Validate against the schema and the current tree, return what would be sent, write nothing. |
</Accordion>

<Accordion title="delete_element" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Delete one element and everything inside it from a page, header or footer. Editor-only (UNKNOWN) widgets can be deleted; form buttons cannot — delete the FORM_ELEMENT instead. The draft changes; nothing goes live.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | Site name (e.g. 'a1b2c3d4'), from list_sites. |
| `target` | string | no | Which element tree: 'page' (default, needs page_uuid), the site 'header', or the site 'footer'. One of: `page`, `header`, `footer`. |
| `page_uuid` | string | no | Page UUID from list_pages. Required when target is 'page'; ignored otherwise. |
| `element_id` | string | yes | Element id from get_page_elements. |
</Accordion>

<Accordion title="move_element" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Move an element to another container or position. parent_id is the destination ('body' for a section on a page, 'header'/'footer' on those targets); next_sibling_id places it before that sibling, omit to append. Editor-only (UNKNOWN) widgets can be moved.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | Site name (e.g. 'a1b2c3d4'), from list_sites. |
| `target` | string | no | Which element tree: 'page' (default, needs page_uuid), the site 'header', or the site 'footer'. One of: `page`, `header`, `footer`. |
| `page_uuid` | string | no | Page UUID from list_pages. Required when target is 'page'; ignored otherwise. |
| `element_id` | string | yes | Element id from get_page_elements. |
| `parent_id` | string | yes | Destination container id. |
| `next_sibling_id` | string | no | Place before this sibling; omit to append at the end. |
</Accordion>

<Accordion title="duplicate_element" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Create a copy of an element (with its children and styling) next to the original, or inside parent_id if given. Returns the new element id and the copy's outline with child ids and summaries, so you can update_elements its content without another read. To place the copy elsewhere, follow with move_element. Preferred over building similar elements from scratch.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | Site name (e.g. 'a1b2c3d4'), from list_sites. |
| `target` | string | no | Which element tree: 'page' (default, needs page_uuid), the site 'header', or the site 'footer'. One of: `page`, `header`, `footer`. |
| `page_uuid` | string | no | Page UUID from list_pages. Required when target is 'page'; ignored otherwise. |
| `element_id` | string | yes | Element id from get_page_elements. |
| `parent_id` | string | no | Container to place the copy in. Default: same parent as the original. |
</Accordion>

<Accordion title="update_elements" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Change existing elements. Send only the props you want to change; the server merges them into the current props (objects deep-merge, arrays replace). To change one value inside a list — a gallery image's alt, one FAQ entry — use `set` with the path search_site_text returned; it edits that entry and leaves the rest of the list alone. Set a value to null to clear it. Up to 200 elements per call — batch related edits. Returns per-element results.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `site_name` | string | yes | Site name (e.g. 'a1b2c3d4'), from list_sites. |
| `target` | string | no | Which element tree: 'page' (default, needs page_uuid), the site 'header', or the site 'footer'. One of: `page`, `header`, `footer`. |
| `page_uuid` | string | no | Page UUID from list_pages. Required when target is 'page'; ignored otherwise. |
| `updates` | array of object | yes |   |
| `updates[].element_id` | string | yes |   |
| `updates[].props` | object | no | Partial \{data, style\}. null clears a key. Arrays replace wholesale. |
| `updates[].name` | string | no |   |
| `updates[].custom_class_names` | array of string | no | Replaces the list. |
| `updates[].connected_data` | object | no | Replaces all bindings of the element. |
| `updates[].set` | array of object | no | Write single values by path, arrays included — the one way to change one entry of a list without resending the whole list. Applied after props. |
| `updates[].anchor` | object or null | no | Make this element a link target — a menu entry or button can then jump to it with href '#name'. Pages only, SECTION elements only. null removes the anchor. |
| `updates[].anchor.id` | string | yes | Anchor name — the #fragment links use, e.g. 'prices'. Becomes the element's id in the page HTML. |
| `updates[].anchor.create_navigation_item` | boolean | no | Also add a menu item that links to this anchor. |
| `updates[].anchor.navigation_title` | string | no | Menu item title. Defaults to the anchor name. |
| `dry_run` | boolean | no | Return the merged props and changed paths without writing. |
</Accordion>

### AEO

<Accordion title="get_aeo_report" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Reads AI Visibility (AEO) data: how often AI answer engines (ChatGPT, Gemini, Perplexity, etc.) mention a brand, against its competitors. Start here for any AI visibility question.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | A website domain or URL, e.g. 'joesplumbing.com' or 'https://www.joesplumbing.com/services'. Only the host is used. |
| `site_name` | string | no | The site alias, when it is already known. |
| `report_id` | string | no | A one-time report id from create_aeo or the report list; starts with 'or_'. |
| `from_date` | string | no | Start date, YYYY-MM-DD (e.g. '2026-08-01'). Default: 30 days before to_date. |
| `to_date` | string | no | End date, YYYY-MM-DD (e.g. '2026-08-31'). Default: today (UTC). |
| `brands` | integer | no | Competitor brands to compare besides the own brand, 0 to 9. Default 4. |
| `chats` | integer | no | Top prompts to sample one answer per engine from, 0 to 10. Default 0 (no sample answers). |
| `models` | array of string | no | Filter to these answer engines, e.g. ['CHAT_GPT']. |
| `geos` | array of string | no | Filter to these country codes, e.g. ['US']. |
| `include_recommendations` | boolean | no | true to add on-site and off-site recommendations. Default false. |
| `sections` | array of string | no | Parts to return: 'visibility', 'prompts', 'recommendations', 'answers', or 'status' or 'usage' alone. Default: the summary of visibility and prompts. |
| `detail` | string | no | 'summary' (default), 'brands' (visibility as a row per brand) or 'full' (every section in full). One of: `summary`, `brands`, `full`. |
| `include_answer_text` | boolean | no | Site reports only: true to keep each sample answer's full text. Default false returns answer_length instead. |
| `limit` | integer | no | Report list only: page size, 1 to 500. Server default 50. |
| `offset` | integer | no | Report list only: number of reports to skip. |
</Accordion>

<Accordion title="create_aeo" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Starts AI Visibility (AEO) for a domain or site. For a Duda site of this account without tracking, it creates a project: ongoing tracking that uses 1 site slot, activated in the background in about 3 to 4 minutes. For a domain that is not a Duda site of this account, or when the user asks for a one-time report, it creates a one-time report: a single analysis that uses 1 report from the plan, with all data available in about 3 to 4 minutes.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | A website domain or URL, e.g. 'summitdental.com'. Only the host is used. |
| `site_name` | string | no | The site alias, when it is already known. |
| `create` | string | no | What to create, after the user agreed. Omit for a preview that creates nothing. One of: `project`, `one_time_report`. |
| `country_code` | string | no | Required for a project: the site's primary market as an ISO country code, e.g. 'US'. For a one-time report: where the target audience lives, which can differ from the business location; omit for the account's country. |
| `brand_name` | string | no | The brand name as AI answers would mention it. |
| `cities` | array of string | no | Cities to track for local visibility, e.g. ['Austin']. |
| `competitors` | array of object | no | Up to 5 competitor brands to track from the start, each with its domain; ask the user for a missing domain. The own brand is never listed here. |
| `competitors[].name` | string | yes | Competitor brand name. |
| `competitors[].domains` | array of string | yes | Required. The competitor's website domains, at least one, e.g. ['luigis.com']. |
| `models` | array of string | no | One-time report only: answer engines to include, e.g. ['CHAT_GPT', 'GEMINI']. Omit for the plan's default set. |
</Accordion>

<Accordion title="manage_aeo_project" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Changes AI Visibility (AEO) tracking of a site that already has it. Read the status with get_aeo_report sections: ['status']. - pause: stop tracking; all data is kept and the site slot is freed. - resume: restart paused tracking; uses 1 site slot (pause frees it again). - refresh: run now, using one of the site's manual refreshes: read how many are left with get_aeo_report sections: ['usage'] and get the user's yes first. Never refresh after a brand name change; it re-scores existing data.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `action` | string | yes | What to do. One of: `pause`, `resume`, `refresh`. |
</Accordion>

<Accordion title="get_aeo_prompts" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Reads the prompts (questions people ask AI assistants) that a site's AI Visibility (AEO) project tracks. Changes nothing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `view` | string | no | What to read. Default 'list'. One of: `list`, `suggestions`, `answers`. |
| `prompt_id` | string | no | answers: the prompt id, from view 'list'. |
| `archived` | boolean | no | list: true for archived prompts instead of active ones. |
| `fields` | array of string | no | list: fields per prompt. Default ['id','text']; ['*'] for the full row. |
| `limit` | integer | no | list: page size, up to 500 (default 25). suggestions: up to 100 (default 10). answers: page size, up to 100 (default 20, or 5 with include_answer_text). |
| `offset` | integer | no | list: prompts to skip. answers: answers to skip (next_offset from the last page). |
| `from_date` | string | no | Start date, YYYY-MM-DD (e.g. '2026-08-01'). Default: 30 days before to_date. |
| `to_date` | string | no | End date, YYYY-MM-DD (e.g. '2026-08-31'). Default: today (UTC). |
| `model` | string | no | answers: one answer engine only. One of: `CHAT_GPT`, `GEMINI`, `GOOGLE_AI_OVERVIEW`, `GOOGLE_AI_MODE`, `PERPLEXITY`, `MICROSOFT_COPILOT`. |
| `detail` | string | no | answers: 'full' adds the newest answers, text replaced by answer_length. One of: `summary`, `full`. |
| `include_answer_text` | boolean | no | answers: true to include the full answer text (implies full). |
</Accordion>

<Accordion title="update_aeo_prompts" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Adds prompts to a site's AI Visibility (AEO) project. Each prompt uses 1 prompt slot; at the limit it fails with AeoPromptsLimitExceeded (slots used and the limit are in get_aeo_report sections: ['usage']). To read prompts use get_aeo_prompts.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `prompts` | array of string | yes | Prompt texts, e.g. ['best pizza in Austin']. |
| `country_code` | string | no | The country to track the prompts in, e.g. 'US'. Default: the project's primary market. |
</Accordion>

<Accordion title="archive_aeo_prompts" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Stops tracking prompts in a site's AI Visibility (AEO) project. Their data is kept and their prompt slots are freed; restore_aeo_prompts tracks them again. Ids that could not be archived are in not_applied.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `prompt_ids` | array of string | yes | Prompt ids from get_aeo_prompts view 'list' (archived: true for archived ones), up to 25. |
</Accordion>

<Accordion title="restore_aeo_prompts" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Tracks archived prompts again in a site's AI Visibility (AEO) project. Each uses 1 prompt slot. Ids that could not be restored are in not_applied.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `prompt_ids` | array of string | yes | Prompt ids from get_aeo_prompts view 'list' (archived: true for archived ones), up to 25. |
</Accordion>

<Accordion title="get_aeo_competitors" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Lists the site's own brand and the competitor brands its AI Visibility (AEO) project compares against, with ids and domains. Changes nothing.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
</Accordion>

<Accordion title="update_aeo_competitors" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Adds a competitor brand to a site's AI Visibility (AEO) project. Up to 10 competitors. Ask the user for the competitor's website domain rather than guessing. To read competitors use get_aeo_competitors.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `name` | string | yes | The competitor brand name. |
| `competitor_domain` | string | yes | The competitor's website domain, e.g. 'capitalrooter.com'. |
</Accordion>

<Accordion title="edit_aeo_competitors" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Renames a competitor of a site's AI Visibility (AEO) project or changes its domain (brand_id, name and/or competitor_domain). The own brand cannot be changed. A changed brand returns 409 for about a minute.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `brand_id` | string | yes | The competitor id, from get_aeo_competitors. |
| `name` | string | no | The competitor brand name. |
| `competitor_domain` | string | no | The competitor's website domain, e.g. 'capitalrooter.com'. |
</Accordion>

<Accordion title="remove_aeo_competitors" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Stops tracking a competitor of a site's AI Visibility (AEO) project; its past data is kept. Content suggestions need one competitor with a domain (AeoCompetitorDomainRequired). The own brand cannot be removed. A changed brand returns 409 for about a minute.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `brand_id` | string | yes | The competitor id, from get_aeo_competitors. |
</Accordion>

<Accordion title="get_aeo_settings" icon="fa-eye">
**Plan:** Basic · **Access:** Read-only

Reads a site's AI Visibility (AEO) settings: the tracked models (answer engines), extra countries (geos) and cities. Changes nothing. Plan slots used and limits are in get_aeo_report sections: ['usage']; to change settings use add_aeo_settings or remove_aeo_settings.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
</Accordion>

<Accordion title="add_aeo_settings" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write

Adds models (answer engines), extra countries (geos) or cities to a site's AI Visibility (AEO) project; values already tracked are skipped. A new model or geo uses a plan slot (see get_aeo_report sections: ['usage']); a new model answers every prompt, and a new geo copies the primary-market prompts. At most 5 cities. At the model limit, remove one first.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `models` | array of string | no | Answer engines, e.g. ['PERPLEXITY']. |
| `geos` | array of string | no | Extra countries (ISO codes), e.g. ['CA']. |
| `cities` | array of string | no | Cities, e.g. ['Round Rock']. |
</Accordion>

<Accordion title="remove_aeo_settings" icon="fa-pen-to-square">
**Plan:** Basic · **Access:** Write (destructive)

Removes models (answer engines), extra countries (geos) or cities from a site's AI Visibility (AEO) project. Removing a geo deletes its prompts for good, so geos are removed last. At least one model must stay.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | The site's domain or URL, e.g. 'joesplumbing.com'. |
| `site_name` | string | no | The site alias, if known. |
| `models` | array of string | no | Answer engines, e.g. ['GEMINI']. |
| `geos` | array of string | no | Extra countries (ISO codes), e.g. ['CA']. |
| `cities` | array of string | no | Cities, e.g. ['Round Rock']. |
</Accordion>