Xyla AI

Shows which Xyla shop this connection acts for and whether it can only read or can also make changes.

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Summarises this Xyla shop: its plan, AI credits left, whether autopilot is on, how many posts wait for approval, the next 3 posts due, and any social account that needs fixing.

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Lists the posts this Xyla shop will publish, day by day, for up to 7 days from a start date (the shop's today if left out). Each post has its platforms, send time in the shop's time zone, type, caption and media links. Posts waiting for approval are not here: use pending_approvals.

{
  "type": "object",
  "properties": {
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "First day to show, as YYYY-MM-DD in the shop's time zone. Defaults to today."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 7,
      "description": "How many days to show, 1 to 7. Defaults to 7."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Lists the posts in this Xyla shop that wait for the merchant's approval before they are scheduled, 12 per page, with captions and media links. When the shop is still on its first batch, returns that batch as one draft: it is approved as a whole, not post by post.

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "Page number, starting at 1. Defaults to 1."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Shows how this Xyla shop's published posts performed over the last 7, 14, 30 or 90 days: reach, views, engagement, followers per account, and the top posts. Same data as the Insights page in Xyla.

{
  "type": "object",
  "properties": {
    "window_days": {
      "type": "integer",
      "enum": [
        7,
        14,
        30,
        90
      ],
      "description": "How many days back to look. Defaults to 30."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Shows each social account connected to this Xyla shop: connected, expiring soon, expired, needs reconnecting, restricted or disconnected, and how many upcoming posts a broken account is blocking.

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Shows the shop's current Xyla settings for one setting group, with the ids change_settings needs and how each field works. Call it without tool to list the setting groups. Read a group before changing it.

{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string",
      "enum": [
        "audience_profile",
        "brand_identity",
        "brand_kit_presentation",
        "content_topics",
        "enhanced_image_branding",
        "excluded_products",
        "holiday_calendar",
        "instructions",
        "language",
        "link_tracking",
        "music_style",
        "post_frequency",
        "post_mix",
        "post_types",
        "posting_schedule",
        "product_notes",
        "product_post_options",
        "product_queue",
        "product_selection",
        "publishing_account_settings",
        "publishing_link_treatment",
        "review_first",
        "template_presentation",
        "tiktok_posting_options",
        "visual_direction",
        "visual_styles",
        "writing_style",
        "logo",
        "outro",
        "post_type_on_off",
        "billing"
      ],
      "description": "The setting group to read. Leave out to list them."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Changes the shop's Xyla settings in one setting group (or a few related ones) and returns each value before and after plus an undo id. Every change in a call applies, or none does. Read the group with get_settings first, and confirm the change with the merchant before calling this. Changes affect posts made from now on, not posts already scheduled or published.

{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string",
      "enum": [
        "audience_profile",
        "brand_identity",
        "brand_kit_presentation",
        "content_topics",
        "enhanced_image_branding",
        "excluded_products",
        "holiday_calendar",
        "instructions",
        "language",
        "link_tracking",
        "music_style",
        "post_frequency",
        "post_mix",
        "post_types",
        "posting_schedule",
        "product_notes",
        "product_post_options",
        "product_queue",
        "product_selection",
        "publishing_account_settings",
        "publishing_link_treatment",
        "review_first",
        "template_presentation",
        "tiktok_posting_options",
        "visual_direction",
        "visual_styles",
        "writing_style",
        "logo",
        "outro",
        "post_type_on_off",
        "billing"
      ],
      "description": "The setting group to change. logo, outro, post_type_on_off, billing cannot be changed from chat; naming one returns the web page to change it on."
    },
    "actions": {
      "type": "array",
      "maxItems": 16,
      "description": "The changes, applied together: all of them or none.",
      "items": {
        "type": "object",
        "properties": {
          "tool": {
            "type": "string",
            "enum": [
              "audience_profile",
              "brand_identity",
              "brand_kit_presentation",
              "content_topics",
              "enhanced_image_branding",
              "excluded_products",
              "holiday_calendar",
              "instructions",
              "language",
              "link_tracking",
              "music_style",
              "post_frequency",
              "post_mix",
              "post_types",
              "posting_schedule",
              "product_notes",
              "product_post_options",
              "product_queue",
              "product_selection",
              "publishing_account_settings",
              "publishing_link_treatment",
              "review_first",
              "template_presentation",
              "tiktok_posting_options",
              "visual_direction",
              "visual_styles",
              "writing_style"
            ],
            "description": "Only to change another setting group in the same all-or-nothing set (for example post_frequency beside post_mix). Defaults to the top-level tool."
          },
          "target_scope": {
            "type": "string",
            "enum": [
              "all",
              "selected"
            ],
            "description": "all for a group with one target (the shop) or to change every target; selected to change only the targets in target_ids."
          },
          "target_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "With selected: target ids exactly as get_settings returns them (a visual style id, an account id)."
          },
          "changes": {
            "description": "Only the fields to change, named as in that group. Leave out fields to keep them as they are.",
            "anyOf": [
              {
                "title": "audience_profile",
                "description": "Casting and audience profile used for future creative generation: who appears on screen, and separately who the shop sells to. Excluding all people requires checking post_types and instructions; casting attributes cannot remove the cast. Targets: The shop audience id.",
                "type": "object",
                "properties": {
                  "customer_persona": {
                    "type": "string",
                    "description": "Prose description of who the shop sells to, shown to the merchant as their target customer profile and read by every concept, caption and music generator."
                  },
                  "preferred_age_min": {
                    "type": "integer",
                    "minimum": 18,
                    "maximum": 80,
                    "description": "Minimum casting age. Adults only, never below 18."
                  },
                  "preferred_age_max": {
                    "type": "integer",
                    "minimum": 18,
                    "maximum": 80,
                    "description": "Maximum casting age, at least the minimum age."
                  },
                  "custom_casting_instructions": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Concrete attributes of the person to cast in a single decision. This field describes the person, not API behavior. Do not duplicate sampling ratios here. The selector has no memory of past casting. Do not ask it to rotate, avoid previous choices or add variety across posts; use ratios for the mix instead. At most 1000 characters."
                  },
                  "preferred_gender_ratios": {
                    "type": "object",
                    "properties": {
                      "female": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "male": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      }
                    },
                    "required": [
                      "female",
                      "male"
                    ],
                    "additionalProperties": false,
                    "description": "Gender sampling percentages as a typed JSON object with keys female, male. Whole numbers totaling 100. These change the future mix, not a guaranteed sequence."
                  },
                  "preferred_ethnicity_ratios": {
                    "type": "object",
                    "properties": {
                      "white": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "black": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "latina_latino": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "east_asian": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "south_asian": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "southeast_asian": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "middle_eastern": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "mixed_race": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "indigenous": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "pacific_islander": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      }
                    },
                    "required": [
                      "white",
                      "black",
                      "latina_latino",
                      "east_asian",
                      "south_asian",
                      "southeast_asian",
                      "middle_eastern",
                      "mixed_race",
                      "indigenous",
                      "pacific_islander"
                    ],
                    "additionalProperties": false,
                    "description": "Primary control for ethnic diversity: ethnicity sampling percentages as a typed JSON object with keys white, black, latina_latino, east_asian, south_asian, southeast_asian, middle_eastern, mixed_race, indigenous, pacific_islander. Whole numbers totaling 100; zero excludes a group from sampling. Adjust the distribution directly instead of asking custom instructions for variety. No guaranteed rotation or exact short-run proportions."
                  },
                  "preferred_aesthetics": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "clean_minimal",
                        "warm_everyday",
                        "workwear_trade",
                        "outdoors_adventure",
                        "sporty_athletic",
                        "urban_trendy",
                        "luxury_refined",
                        "bohemian_earthy",
                        "edgy_alternative",
                        "corporate_professional",
                        "coastal_laidback",
                        "soft_romantic",
                        "vintage_retro",
                        "playful_bold"
                      ]
                    },
                    "maxItems": 3,
                    "description": "Selected casting aesthetics."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "brand_identity",
                "description": "How the shop presents itself: the name in captions, how voices say that name aloud in videos, its hashtags, and whether prices show. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "business_name": {
                    "type": "string",
                    "description": "The business name used in captions. Only change this when the merchant says it is wrong."
                  },
                  "business_name_pronunciation": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "How voices say the business name aloud in videos. The lever for every complaint that a video says the name wrong. At most 80 characters."
                  },
                  "domain": {
                    "type": "string",
                    "description": "The shop's website address, stored without https://."
                  },
                  "types_of_products": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "What the shop sells, in a few plain words each (for example \"candles\", \"running shoes\")."
                  },
                  "use_business_name": {
                    "type": "boolean",
                    "description": "Whether captions name the business at all."
                  },
                  "include_hashtags": {
                    "type": "boolean",
                    "description": "Whether captions carry hashtags at all."
                  },
                  "default_hashtags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Hashtags added to every caption, without the leading #."
                  },
                  "display_pricing": {
                    "type": "boolean",
                    "description": "Whether captions show the product price."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "brand_kit_presentation",
                "description": "Presentation colors and an existing-logo watermark for ONE brand kit. Uploading or replacing the logo itself is a merchant action in Brand kit; use the brand_kit_logo support response and destination for that request. Targets: The existing shop brand kit id.",
                "type": "object",
                "properties": {
                  "primary_color": {
                    "type": "string",
                    "description": "Primary six-digit brand color."
                  },
                  "text_color": {
                    "type": "string",
                    "description": "Text six-digit brand color."
                  },
                  "default_video_logo_watermark_enabled": {
                    "type": "boolean",
                    "description": "Use the already-uploaded logo as a video watermark."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "content_topics",
                "description": "What the shop talks about, what it must never talk about, and how it sounds doing it. Built from the catalogue when it was last derived, so it can still name products the store has since removed. List fields are STATE, not a delta: send the whole list you want the shop to end up with. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "forbidden_subjects": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Subjects the shop must never post about. Send the full list, existing entries included."
                  },
                  "domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The topic areas the shop's content covers, by label (for example \"Skincare\"). Send the full list, existing entries included."
                  },
                  "voice_hint": {
                    "type": "string",
                    "description": "One or two sentences describing the tone of the shop's content."
                  },
                  "audience_attention_pattern": {
                    "type": "string",
                    "description": "One or two sentences describing who the audience is and what makes them stop scrolling."
                  },
                  "pricepoint_tier": {
                    "type": "string",
                    "enum": [
                      "budget",
                      "mid",
                      "premium",
                      "luxury",
                      "unknown"
                    ],
                    "description": "The shop's actual price positioning. Change only when the merchant asks to correct that positioning, not to make copy more professional or to prefer higher-value products. Use voice_hint, writing_style or instructions for tone."
                  },
                  "active_modes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "narrative_video",
                        "fact",
                        "quote",
                        "meme",
                        "quiz",
                        "educational"
                      ]
                    },
                    "description": "Which non-product formats actually run. fact, quote, meme and quiz enable their PostTypeShop categories and eligible templates; adding categories broadens a small content mix. narrative_video enables Narratives and educational enables educational videos in the stories_guides AI channel. Pair these video modes with a nonzero AI video budget and stories_guides weight in post_mix; the forecast shows whether autopilot can produce them. For a studio shop, fact, quote and quiz are the studio's own posts (any one on keeps studio posts running) and their themes are not used. Send the full list, preserving existing modes."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "enhanced_image_branding",
                "description": "The shop's default branding on AI images: website address, business name, logo watermark or nothing. Covers \"put my website on my images\" and \"take the branding off\". Per-style overrides are visual_styles brand_reference_mode. It adds the shop's own mark beside the product; print, labels or logos missing from the product itself are a product accuracy defect, not branding. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "default_mode": {
                    "type": "string",
                    "enum": [
                      "none",
                      "smart_auto",
                      "domain",
                      "business_name",
                      "logo_watermark_only"
                    ],
                    "description": "What branding AI images carry by default."
                  },
                  "no_text_treatment": {
                    "type": "string",
                    "enum": [
                      "clean",
                      "logo_watermark"
                    ],
                    "description": "What happens on an image whose style carries no text at all."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "excluded_products",
                "description": "Products automatic selection must never use, e.g. discontinued items still listed in the store or a brand the merchant no longer wants posted. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "excluded_products": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 200,
                    "description": "The complete list of excluded products. Each entry is \"Title (#id)\", a bare product id, or a search phrase that adds every matching product. Entries left out are no longer excluded."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "holiday_calendar",
                "description": "Holiday posts: whether the shop posts on holidays at all, which country's calendar it follows, and which dates it celebrates. Covers \"stop posting about holidays\", the wrong country's holidays, and celebrating only certain ones. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "holiday_posts_enabled": {
                    "type": "boolean",
                    "description": "Whether the Holiday post type runs at all."
                  },
                  "holidays_iso": {
                    "type": "string",
                    "description": "Two-letter country code for the holiday calendar, such as US or GB."
                  },
                  "holiday_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The holidays the shop celebrates, by id, from the candidate options for its country."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "instructions",
                "description": "Standing free-text direction the shop's generators read before every video, image and caption: scene direction, taste and tone. It cannot put words, web addresses or logos on screen, and a link or web address in captions is publishing_link_treatment, never these fields. Spoken accents go to language first; casting ages and demographic ratios go to audience_profile. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "creative_concept_instructions": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Creative direction for Enhanced product videos: what the scenes should show, who should appear in them, what to avoid. At most 2000 characters."
                  },
                  "enhanced_image_creative_concept_instructions": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Creative direction for Enhanced product images, including who appears in them. At most 2000 characters."
                  },
                  "ugc_creative_concept_instructions": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Creative direction for UGC scenes and the manner of the person on camera and the setting they film in, including spoken accent and delivery. Use audience_profile for demographic casting settings. At most 2000 characters."
                  },
                  "narrative_creative_concept_instructions": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Creative direction for Story videos, the narrated storytelling ones, including spoken narration accent and delivery. At most 2000 characters."
                  },
                  "caption_generation_instructions": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Standing direction for how captions are written for every post: tone, length, what to mention, what to leave out. At most 2000 characters."
                  },
                  "custom_caption_instructions": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Extra caption direction appended to the above, and where a standing line for every caption goes, such as an ongoing discount. At most 500 characters."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "language",
                "description": "The shop's posts and audio dialogue language, including regional dialects. Primary control for spoken accent requests when a matching language variant exists, such as British English. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "language_id": {
                    "type": "integer",
                    "description": "ID of an available language/dialect option. Read the current language and select the requested variant from candidates; never invent an ID."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "link_tracking",
                "description": "UTM tracking added to the links Xyla publishes, so the merchant's analytics can tell Xyla traffic apart. For measuring or attributing the traffic and sales these posts bring. Whether a link appears at all is publishing_link_treatment. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "social_post_utm_params": {
                    "type": "string",
                    "description": "Tracking parameters added to product links in posts, as a query string without the leading \"?\"."
                  },
                  "bio_utm_params": {
                    "type": "string",
                    "description": "The same, for links on the Link in bio storefront. Set both when the merchant wants all Xyla traffic labeled, and keep the campaign names different if they want to tell posts and bio clicks apart."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "music_style",
                "description": "The sound under the shop's videos: the music style direction and whether videos have sound at all. Covers music and sung vocals, not spoken narration or presenter accents. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "mute_all_video_audio": {
                    "type": "boolean",
                    "description": "Silences every future video: no music, and no spoken audio either."
                  },
                  "music_prompt": {
                    "type": "string",
                    "maxLength": 600,
                    "description": "Full replacement Music style text, at most 600 characters. Covers genre, mood, energy, instruments, vocals and lyric restrictions; vague is fine. Preserve existing compatible genre/mood preferences while incorporating the requested change. For clean lyrics, explicitly exclude offensive or explicit lyrics without removing all vocals unless requested. Empty text clears the custom preference. At most 600 characters."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "post_frequency",
                "description": "How often the shop posts, and how much of that is product content rather than blogs, facts, quizzes and other non-product posts. Structural: it changes the next batch and does not alter posts that already exist. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "post_frequency_days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 30,
                    "description": "Post one batch every this many days. The plan may refuse a value it does not allow."
                  },
                  "posts_per_day": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "description": "How many posts go out on a posting day. The plan may refuse a value it does not allow."
                  },
                  "product_post_frequency": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 7,
                    "description": "How much of the schedule is product content, on a dial from 0 to 7: 0 is no product posts, 3 is about half of them, 7 is every post."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "post_mix",
                "description": "Controls future media allocation across template videos, AI video channels, AI images and shop photos. The allocation forecast reports effective counts, quotas, capacity and reasons for shortfalls. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "allow_ai_images": {
                    "type": "boolean",
                    "description": "Shop-level permission for AI images. Effective AI images require this permission, Product enhanced_images enabled, an eligible plan and a nonzero monthly_ai_image_count."
                  },
                  "monthly_video_count": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 200,
                    "description": "How many videos a month the shop gets. Clamped to what its plan allows."
                  },
                  "enhanced_video_percentage": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "The share of those videos that are AI rendered rather than made from templates. Clamped to what its plan allows. Shops on AI budgets read this as a count instead, so prefer monthly_ai_video_count."
                  },
                  "monthly_ai_video_count": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 200,
                    "description": "How many AI videos a month the shop gets. The rest of its videos are made from templates. Clamped to what its plan and its product posts allow. Empty means the merchant never chose: it follows allocation_forecast.ai_video_cap as plans and product slots change. Keep it empty unless the merchant asks for a number of AI videos; a total video change alone does not."
                  },
                  "monthly_ai_image_count": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 400,
                    "description": "How many AI images a month the shop gets. The rest of its product posts use its own photos. Pair increased AI images with fewer total videos when replacing template videos. Clamped to what its plan and its product posts allow. Empty means the merchant never chose and it follows allocation_forecast.ai_image_cap; keep it empty unless the merchant asks about AI images."
                  },
                  "video_mix_weights": {
                    "type": "object",
                    "properties": {
                      "enhanced": {
                        "type": "number",
                        "minimum": 0
                      },
                      "trending": {
                        "type": "number",
                        "minimum": 0
                      },
                      "ugc": {
                        "type": "number",
                        "minimum": 0
                      },
                      "podcast": {
                        "type": "number",
                        "minimum": 0
                      },
                      "stories_guides": {
                        "type": "number",
                        "minimum": 0
                      }
                    },
                    "required": [
                      "enhanced",
                      "trending",
                      "ugc",
                      "podcast",
                      "stories_guides"
                    ],
                    "additionalProperties": false,
                    "description": "Relative weights per video channel, sent as a JSON object. Channels are enhanced, trending, ugc, podcast, stories_guides. Send every channel the shop should keep."
                  },
                  "include_ai_disclosure_hashtag": {
                    "type": "boolean",
                    "description": "Adds the #AI hashtag to captions, on posts whose media puts a person on screen."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "post_types",
                "description": "Which kinds of media the shop's product posts are allowed to be, plus burned-in subtitles, outro cards and product-photo first frames. Structural: it changes the next batch. Use these switches for exclusions incompatible with a format, such as no people. Some of these need a Pro plan and the save will be refused without one. Targets: Which post type to change. Use \"Product\" unless told otherwise.",
                "type": "object",
                "properties": {
                  "enhanced_videos": {
                    "type": "boolean",
                    "description": "AI rendered product videos."
                  },
                  "ugc_videos": {
                    "type": "boolean",
                    "description": "UGC style videos with a person on camera."
                  },
                  "podcast_videos": {
                    "type": "boolean",
                    "description": "Podcast videos with two visible hosts. Requires people on screen, not voiceover-only audio."
                  },
                  "enhanced_images": {
                    "type": "boolean",
                    "description": "AI rendered product images. Also requires post_mix allow_ai_images and a nonzero AI image budget on an eligible plan."
                  },
                  "trending_videos": {
                    "type": "boolean",
                    "description": "AI videos built from changing TikTok trends. Requires a nonzero AI video budget and a trending allocation in post_mix to produce posts."
                  },
                  "default_video_captions": {
                    "type": "boolean",
                    "description": "Burned-in subtitles on videos. On is usually right, because most feeds autoplay muted. Turn off when a merchant asks for no text on videos or says text covers the product."
                  },
                  "product_image_as_first_frame": {
                    "type": "boolean",
                    "description": "Whether a real catalogue photo is the video's first frame, anchoring what follows to the actual product."
                  },
                  "outro_videos": {
                    "type": "boolean",
                    "description": "A closing brand card at the end of videos. Turn on for brand recall, off when a merchant says videos end on a logo instead of the product. The card itself is designed in Brand kit."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "posting_schedule",
                "description": "Future posting time and timezone. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "post_hour": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 23,
                    "description": "Hour for future scheduled posts."
                  },
                  "post_timezone": {
                    "type": "integer",
                    "minimum": -12,
                    "maximum": 14,
                    "description": "UTC offset for future scheduled posts."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "product_notes",
                "description": "A note about ONE product that its photos and description do not make clear, read by every image, video and caption made for that product. Targets: Which product. Use an id from this tool's current products, or from a referenced post's products.",
                "type": "object",
                "properties": {
                  "note": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Plain facts about how this product looks or is used, in the merchant's terms. At most 500 characters."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "product_post_options",
                "description": "How a product post is built once the products are chosen: which catalogue photo it features (the cover, a mock-up, a collage), whether photos change between posts, one product or several, whether #ad leads the caption, and the call-to-action lines rotated into product captions. Which products get posted is product_selection. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "product_image_index": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "description": "Which catalogue photo to feature, counting from 1 for the cover photo."
                  },
                  "cover_product_image_only": {
                    "type": "boolean",
                    "description": "Only ever use the product's cover photo."
                  },
                  "rotate_product_images": {
                    "type": "boolean",
                    "description": "When a product has been posted before, feature a different photo next time."
                  },
                  "randomize_product_images": {
                    "type": "boolean",
                    "description": "Shuffle the photo order inside multi-image product posts. Tradeoff: the merchant loses the deliberate order they set in their store."
                  },
                  "random_product_posts": {
                    "type": "boolean",
                    "description": "Pick products at random rather than favoring new arrivals and bestsellers."
                  },
                  "single_product_posts_only": {
                    "type": "boolean",
                    "description": "Every product post features exactly one product rather than a group."
                  },
                  "include_ad_hashtag": {
                    "type": "boolean",
                    "description": "Put #ad first in every product caption."
                  },
                  "link_in_bio_messages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 10,
                    "description": "Call-to-action lines rotated into product captions, at most 10 and 120 characters each."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "product_queue",
                "description": "The exact products upcoming Autopilot product posts use, in order, and which of them repeat (Evergreen). Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "queue_products": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 50,
                    "description": "The complete ordered queue. Each entry is a product from this tool's state as \"Title (#id)\", or the product's title as the merchant wrote it, which is looked up in the store. Entries left out are removed."
                  },
                  "evergreen_products": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 50,
                    "description": "The complete list of queued products that repeat (Evergreen), written the same way. Every one must also be in queue_products."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "product_selection",
                "description": "Collection and stock filters for automatic product selection. Selection only ever uses products the store currently lists as active. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "exclude_seasonal_products": {
                    "type": "boolean",
                    "description": "Enable the existing out-of-season product safeguard. It includes holiday keyword checks and available product-profile restrictions, not reliable season-by-season merchandising. Does not reliably select seasonal plants or rotate collections. For seasonal selection advice use the seasonal_product_selection procedure, which checks this flag and explains the product queue and collection filters."
                  },
                  "allow_out_of_stock_products": {
                    "type": "boolean",
                    "description": "Whether future product selection may include products the platform reports as unavailable. False is a strict stock filter, including when other filters are relaxed. Does not remove already scheduled posts."
                  },
                  "product_collection_filter_mode": {
                    "type": "string",
                    "enum": [
                      "allowlist",
                      "denylist"
                    ],
                    "description": "How the collection list is read. allowlist means products are only ever picked from the listed collections. denylist means products are never picked from them. With no collection IDs, no collection filter is applied in either mode."
                  },
                  "product_collection_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The platform collection ids the mode applies to. Send the FULL list, existing entries included. Clear the filter with an IDs-only product_collection_ids: [] change, so every collection is in play. An explicit allowlist together with an empty list is rejected because it cannot identify the promised collection. Only use ids from the shop's available collections."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "publishing_account_settings",
                "description": "Provider- and plan-eligible publishing settings for ONE connected account. Targets: The connected account id.",
                "type": "object",
                "properties": {
                  "active_posting": {
                    "type": "boolean",
                    "description": "Whether posts actually publish to this account, including ones already scheduled. Turn it off to pause one platform without touching the rest. Tradeoff: posts still get generated and scheduled, they just stop going out here."
                  },
                  "custom_link_text": {
                    "type": "string",
                    "description": "The closing line Instagram or TikTok captions use in place of a clickable link."
                  },
                  "post_to_instagram_stories": {
                    "type": "boolean",
                    "description": "Also publish eligible Instagram posts to Stories."
                  },
                  "product_collection_filter_mode": {
                    "type": "string",
                    "enum": [
                      "all",
                      "selected",
                      "none"
                    ],
                    "description": "How this account filters product posts."
                  },
                  "product_collection_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Complete collection ids for the account filter."
                  },
                  "disclose_ai_synthetic_content": {
                    "type": "boolean",
                    "description": "Declares AI-generated media to the platform itself, which labels the post."
                  },
                  "default_hashtags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Hashtags for THIS account only, replacing the shop-wide defaults on it."
                  },
                  "product_tagging": {
                    "type": "boolean",
                    "description": "Tag the products shown in Instagram posts so people can tap through to buy. Needs an eligible Instagram account with a connected shop, on Scale."
                  },
                  "excluded_content_kinds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "product_post",
                        "enhanced_image",
                        "enhanced_video",
                        "studio",
                        "ugc",
                        "trending",
                        "stories",
                        "podcast",
                        "meme",
                        "blog",
                        "holiday",
                        "fact",
                        "quote",
                        "quiz"
                      ]
                    },
                    "description": "Kinds of autopilot post this account does NOT receive. Empty means it gets every kind."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "publishing_link_treatment",
                "description": "The provider-specific setting that controls link treatment for ONE connected social account. Instagram, TikTok, and YouTube read link_mode; Facebook and X read link_in_bio_cta. Pinterest has no supported no-link control. A request to show the store's link or web address in captions comes here. Targets: Which connected social account to change. Use an id from the shop's current eligible accounts.",
                "type": "object",
                "properties": {
                  "link_mode": {
                    "type": "string",
                    "enum": [
                      "cta",
                      "plain_link",
                      "custom",
                      "none"
                    ],
                    "description": "The caption link treatment for Instagram or TikTok; YouTube permits cta, plain_link, or none. none suppresses it."
                  },
                  "link_in_bio_cta": {
                    "type": "boolean",
                    "description": "The legacy Facebook or X setting that suppresses their normal link behavior when true."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "review_first",
                "description": "Review first, the approval gate: whether a newly created post waits for the merchant to approve it or goes straight onto the schedule. Off is Hands-off, where Xyla posts without asking. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "require_post_approval": {
                    "type": "boolean",
                    "description": "True means every new post waits for approval. False is Hands-off: posts publish on schedule without asking."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "template_presentation",
                "description": "ONE image template's design, colours, font and logo. Which catalogue photo shows is product_post_options. Targets: The existing template configuration id.",
                "type": "object",
                "properties": {
                  "background_color": {
                    "type": "string",
                    "description": "Template background color."
                  },
                  "image_template_id": {
                    "type": "integer",
                    "description": "Existing image template id."
                  },
                  "font_color": {
                    "type": "string",
                    "description": "Template font color."
                  },
                  "font_family": {
                    "type": "string",
                    "description": "Template font family."
                  },
                  "logo": {
                    "type": "boolean",
                    "description": "Show the existing uploaded logo."
                  },
                  "logo_background": {
                    "type": "boolean",
                    "description": "Show a background behind the existing logo."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "tiktok_posting_options",
                "description": "TikTok's own publishing settings for ONE connected TikTok account: who can see the videos, which viewer interactions are allowed, TikTok's commercial disclosure, and whether TikTok adds its own music. Provider settings: they change nothing about how a video is made. Targets: Which connected TikTok account to change. Use an id from the shop's current TikTok accounts.",
                "type": "object",
                "properties": {
                  "privacy_level": {
                    "type": "string",
                    "enum": [
                      "PUBLIC_TO_EVERYONE",
                      "MUTUAL_FOLLOW_FRIENDS",
                      "SELF_ONLY"
                    ],
                    "description": "Who can see published videos."
                  },
                  "disable_comment": {
                    "type": "boolean",
                    "description": "Turn comments off on published videos."
                  },
                  "disable_duet": {
                    "type": "boolean",
                    "description": "Stop viewers making Duets with the videos. Tradeoff: Duets are free reach from other people's audiences."
                  },
                  "disable_stitch": {
                    "type": "boolean",
                    "description": "Stop viewers Stitching clips of the videos. Tradeoff: the same loss of borrowed reach as Duets."
                  },
                  "brand_organic_toggle": {
                    "type": "boolean",
                    "description": "Declare to TikTok that the video promotes the merchant's own brand. This is what a store's own product videos are, so it is the usual one to turn on. Commercial disclosure, separate from AI disclosure."
                  },
                  "brand_content_toggle": {
                    "type": "boolean",
                    "description": "Declare that the video promotes a third party in exchange for something of value. Branded content. Only true when the merchant really is paid to promote someone else."
                  },
                  "auto_add_music": {
                    "type": "boolean",
                    "description": "Let TikTok add a trending track of its own to each post."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "visual_direction",
                "description": "Create new visual styles, or rewrite an existing one, from the merchant's direction about how AI images and videos should look; the full style is written from it. Targets: new to create styles, or the id of the existing style to revise.",
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": [
                      "create",
                      "revise"
                    ],
                    "description": "create new styles, or revise the targeted one."
                  },
                  "direction": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "What the merchant wants, in their words, what they disliked about what they saw, and what to keep. At most 1000 characters."
                  },
                  "existing_styles": {
                    "type": "string",
                    "enum": [
                      "replace",
                      "keep",
                      "keep_some"
                    ],
                    "description": "create only: replace switches every existing style off, keep leaves them all on, keep_some leaves on only keep_style_ids."
                  },
                  "keep_style_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 10,
                    "description": "keep_some only: ids of the existing styles that stay on beside the new look."
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 3,
                    "description": "create only: how many styles to build in the new look."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "visual_styles",
                "description": "Enable or disable ONE existing visual style, or fine-tune its settings: how real or produced its photography is, what job it does, and its text, call to action and branding treatment. A visual style is a look its Enhanced videos and images are made in; it does not control template videos or the AI video channel mix. Targets: Which visual style to change. Use an id from the shop's current styles.",
                "type": "object",
                "properties": {
                  "active": {
                    "type": "boolean",
                    "description": "Whether this style is used for future Enhanced images and videos. Disabling removes this look from the available pool; enabling adds it. This does not change template quotas or AI channel allocations. Keep at least one suitable style active."
                  },
                  "text_approach": {
                    "type": "string",
                    "enum": [
                      "NEVER",
                      "TAGLINE_ONLY",
                      "WHEN_ENHANCES",
                      "DESIGNED_AD"
                    ],
                    "description": "How much written text may appear in the frame. NEVER is no text at all, TAGLINE_ONLY is one short line, WHEN_ENHANCES is text only where it helps, DESIGNED_AD is a fully designed ad."
                  },
                  "cta_style": {
                    "type": "string",
                    "enum": [
                      "subtle",
                      "bold",
                      "overlay-text",
                      "integrated-graphic",
                      "none"
                    ],
                    "description": "How a call to action is presented in the image."
                  },
                  "annotations": {
                    "type": "boolean",
                    "description": "Whether small explanatory callouts may be drawn onto the image."
                  },
                  "brand_reference_mode": {
                    "type": "string",
                    "enum": [
                      "inherit",
                      "none",
                      "smart_auto",
                      "domain",
                      "business_name"
                    ],
                    "description": "Which brand mark appears in the image: the website domain, the business name, smart_auto to let the system pick, none for no branding, or inherit for the shop default."
                  },
                  "photographic_reality": {
                    "type": "string",
                    "enum": [
                      "AUTHENTIC_ADVENTURE",
                      "PREMIUM_EDITORIAL",
                      "AUTHENTIC_CASUAL",
                      "CLEAN_CONTEMPORARY",
                      "PRODUCT_HERO_EDITORIAL",
                      "SURREAL_EDITORIAL",
                      "RAW_DOCUMENTARY",
                      "AUTHENTIC_IN_USE",
                      "CLEAN_FASHION_EDITORIAL"
                    ],
                    "description": "How real or how produced the imagery looks. RAW_DOCUMENTARY, AUTHENTIC_CASUAL, AUTHENTIC_IN_USE and AUTHENTIC_ADVENTURE look like a real photograph somebody took. PREMIUM_EDITORIAL, PRODUCT_HERO_EDITORIAL, CLEAN_FASHION_EDITORIAL and SURREAL_EDITORIAL look staged or produced. CLEAN_CONTEMPORARY sits between the two."
                  },
                  "creative_role": {
                    "type": "string",
                    "enum": [
                      "authentic_use",
                      "product_hero",
                      "proof_comparison",
                      "lifestyle_context",
                      "distinctive_world",
                      "information_design"
                    ],
                    "description": "What job the style does. authentic_use is real use and lifestyle_context is everyday settings, the natural ones. information_design is the explainer, a designed ad with callouts, claims and a call to action. product_hero is a controlled product shot, proof_comparison is before and after evidence, distinctive_world is a stylized world."
                  }
                },
                "additionalProperties": false
              },
              {
                "title": "writing_style",
                "description": "Which of the shared writing styles the shop's captions are written in. Targets: the shop, so use target_scope all.",
                "type": "object",
                "properties": {
                  "writing_style_id": {
                    "type": "integer",
                    "description": "The id of a writing style from the list of styles available to the shop."
                  }
                },
                "additionalProperties": false
              }
            ]
          }
        },
        "required": [
          "target_scope",
          "changes"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "tool",
    "actions"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Puts back the settings a change set replaced, using the undo id from change_settings or change_history. The whole set is undone, or nothing is. It is refused when a setting has changed again since, so a newer choice is never overwritten.

{
  "type": "object",
  "properties": {
    "undo_id": {
      "type": "string",
      "description": "The undo id, exactly as change_settings or change_history gave it."
    }
  },
  "required": [
    "undo_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Lists recent changes to the shop's Xyla settings, newest first: what changed, before and after, who made it (the merchant, Xyla or the assistant), and the undo id to pass to undo_change.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "How many changes to list. Defaults to 10."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Makes a one-use link that connects a social account to this Xyla shop, or reconnects a broken one. Give the merchant the link to open in their browser; it works once and expires in 10 minutes, and asks for the store's email. To reconnect an account from connection_status, pass its social_media_account_id. Instagram has two ways in: instagram_direct (Instagram Login, the usual choice) and instagram (through a Facebook Page, needed for Stories and product tags). Disconnecting stays on the Xyla website.

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "instagram",
        "instagram_direct",
        "facebook",
        "x",
        "tiktok",
        "pinterest",
        "youtube",
        "threads"
      ],
      "description": "The platform to connect."
    },
    "social_media_account_id": {
      "type": "integer",
      "description": "The account to reconnect, from connection_status. Leave out to connect a new account."
    }
  },
  "required": [
    "provider"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Approves posts in this Xyla shop that are waiting for approval, by their IDs from pending_approvals. Each approved post takes the next free slot in the schedule; nothing publishes straight away. Posts in the shop's first batch cannot be approved one by one: use approve_first_batch for those.

{
  "type": "object",
  "properties": {
    "post_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "The IDs of the posts to approve, from pending_approvals."
    }
  },
  "required": [
    "post_ids"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Rejects one post in this Xyla shop that is waiting for approval, by its ID from pending_approvals. The post is cancelled and will not be published.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "integer",
      "description": "The ID of the post to reject, from pending_approvals."
    }
  },
  "required": [
    "post_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Approves this Xyla shop's first batch of posts as a whole. When the shop can publish, this also turns autopilot on in include mode (the posts already made are scheduled and nothing is deleted), and releases posts held for review into the schedule. Posts go out at their scheduled times, not straight away.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Starts a fix for one post's image or video in this Xyla shop. Xyla first checks the media for a problem on its side, which makes the fix free; otherwise the fix costs credits. Nothing is changed or charged yet. Then call post_fix_status with the audit_id to learn the cost, tell the merchant, and call confirm_post_fix only once they agree.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "integer",
      "description": "The ID of the post to fix."
    },
    "what_to_change": {
      "type": "string",
      "maxLength": 2000,
      "description": "What the merchant wants changed, in their words."
    }
  },
  "required": [
    "post_id",
    "what_to_change"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Reports where a post fix from request_post_fix stands in this Xyla shop: still being checked, free (Xyla found a problem on its side), or how many credits it costs. After confirm_post_fix, reports whether the fix is running, done or failed.

{
  "type": "object",
  "properties": {
    "audit_id": {
      "type": "integer",
      "description": "The audit_id from request_post_fix."
    }
  },
  "required": [
    "audit_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Runs a post fix that request_post_fix started in this Xyla shop, with the change the merchant asked for. Call post_fix_status first and tell the merchant whether it is free or what it costs; a fix that is not free uses the shop's credits. The new image or video replaces the post's media when it is ready.

{
  "type": "object",
  "properties": {
    "audit_id": {
      "type": "integer",
      "description": "The audit_id from request_post_fix."
    }
  },
  "required": [
    "audit_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Turns Xyla autopilot on or off for this shop. With autopilot on, Xyla makes and schedules posts by itself. mode include (the default) keeps posts already made and adds them to the schedule. mode fresh DELETES every post not yet scheduled, including posts the merchant made by hand, then builds a new schedule: call it first without confirm_delete_count to get the number of posts it deletes, tell the merchant, and only after they agree call again with confirm_delete_count set to that number. Turning autopilot off unschedules upcoming posts and deletes nothing.

{
  "type": "object",
  "properties": {
    "on": {
      "type": "boolean",
      "description": "true turns autopilot on, false turns it off."
    },
    "mode": {
      "type": "string",
      "enum": [
        "include",
        "fresh"
      ],
      "default": "include",
      "description": "Only when turning on. include keeps existing posts; fresh deletes unscheduled posts first."
    },
    "confirm_delete_count": {
      "type": "integer",
      "minimum": 0,
      "description": "Fresh mode only: the number of posts to delete, from the previous set_autopilot reply, after the merchant agreed."
    }
  },
  "required": [
    "on"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Shows what Xyla would post for an online store, with no Xyla account. Give it the store's web address (Shopify or WooCommerce). Xyla reads the store's brand (logo, colours, niche) and makes 3 sample social media posts from the store's own product photos, with captions. Returns a preview token at once; the posts take about 3 minutes and the card shows them as they finish. A store previewed in the last 7 days gets its earlier samples back. When no card is shown, call preview_status with the token to follow it. A store that already uses Xyla gets a sign-in link instead.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2000,
      "description": "The store's web address, such as yourstore.com or yourstore.myshopify.com."
    }
  },
  "required": [
    "url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Checks a store preview started with preview_store: the brand Xyla found and the sample posts finished so far. done is true once the preview is ready or has stopped. While the preview card is showing it updates itself, so only call this when no card is shown, every few seconds.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "maxLength": 64,
      "description": "The preview token preview_store returned."
    }
  },
  "required": [
    "token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}