{
  "type": "object",
  "properties": {
    "groups": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Groups to switch on, e.g. ['ads']. Unknown names are refused by name rather than ignored."
    }
  },
  "required": [
    "groups"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "description": "words from the task or the tool name, e.g. \"lead form\", \"whatsapp\", \"google ads keyword\", \"meta insights\"",
      "type": "string"
    },
    "group": {
      "description": "limit to one group: core, research, create, channels, channel_admin, analytics, ads, files, workspace",
      "type": "string"
    },
    "limit": {
      "description": "how many to return (default 12, max 40)",
      "type": "number"
    },
    "onlyHealthy": {
      "description": "leave out tools that are failing their recent calls or that need a connector this workspace has not made. Default false — nothing is hidden unless you ask, because a missing row reads as a missing capability.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "the tool name exactly as find_tools returned it, e.g. create_meta_lead_form"
    },
    "args": {
      "description": "the tool's arguments as an object, exactly as its own schema takes them",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "account": {
      "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one bluesky account connected (several and none named is refused by name, never guessed); omit when there is one.",
      "type": "string"
    },
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "the post's angle — a list_hooks id or your own wording, reused exactly",
      "type": "string"
    },
    "subject": {
      "description": "what the post is about",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "idempotencyKey": {
      "description": "any stable string: a repeat within 24h returns the original post instead of posting again",
      "type": "string"
    },
    "allowDuplicate": {
      "description": "post it even though an identical post was just made",
      "type": "boolean"
    },
    "text": {
      "type": "string",
      "description": "The post, up to 300 characters / 3000 UTF-8 bytes."
    },
    "imageUrls": {
      "description": "Up to 4 public image URLs to attach. Cannot be combined with videoUrl.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "altText": {
      "description": "Alt text — an ARRAY, one per image in the same order, or a single STRING to describe every image with it. WRITE ONE: Bluesky’s own lexicon makes `alt` a REQUIRED property of every image, so a post without it is undescribed by design rather than by omission, and Bluesky users expect it. No maximum length is published, so nothing is truncated.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "videoUrl": {
      "description": "One public MP4 URL. Cannot be combined with imageUrls. Bluesky transcodes it, which takes a minute or two.",
      "type": "string"
    },
    "videoAlt": {
      "description": "Alt text describing the video, for accessibility.",
      "type": "string"
    },
    "captions": {
      "description": "Up to 20 WebVTT caption tracks: [{lang:'en', url:'https://…/en.vtt'}] or [{lang:'en', content:'WEBVTT\\n\\n00:00…'}]. Each file is capped at 20000 bytes.",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "langs": {
      "description": "BCP-47 language tags, e.g. ['en'].",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "linkCard": {
      "description": "Rich link card (`app.bsky.embed.external`). OMIT for the default (a card is built automatically when the post has a URL and no media). `false` never builds one. `true` builds one from the first URL in the text. An object {uri,title,description,thumbUrl} overrides any field — supply BOTH title and description and the page is never fetched. Cannot be combined with imageUrls/videoUrl: a post has ONE embed, so an explicit linkCard beside media is refused.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        }
      ]
    },
    "platformCover": {
      "description": "VIDEO COVER. Bluesky has no cover setting and shows the video’s FIRST frame, so by default Hermoso checks it and, only when that frame is blank (a template ad’s empty opening card), sends Bluesky a copy with the first frame replaced by the video’s best frame. Your Library file is never changed. true = send the file exactly as it is.",
      "type": "boolean"
    }
  },
  "required": [
    "text"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "account": {
      "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one telegram account connected (several and none named is refused by name, never guessed); omit when there is one.",
      "type": "string"
    },
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "the post's angle — a list_hooks id or your own wording, reused exactly",
      "type": "string"
    },
    "subject": {
      "description": "what the post is about",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "idempotencyKey": {
      "description": "any stable string: a repeat within 24h returns the original post instead of posting again",
      "type": "string"
    },
    "allowDuplicate": {
      "description": "post it even though an identical post was just made",
      "type": "boolean"
    },
    "chatId": {
      "type": "string",
      "description": "REQUIRED — the destination: a public channel's @username, or the numeric chat id. Never guessed; ask the user, or use list_telegram_chats."
    },
    "text": {
      "description": "the message. ≤4096 characters on its own; ≤1024 once any image or video is attached.",
      "type": "string"
    },
    "imageUrl": {
      "description": "one image (≤10MB after upload)",
      "type": "string"
    },
    "imageUrls": {
      "description": "an ALBUM of 2–10 media, in order. Photos and videos may be mixed — Telegram allows it.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "videoUrl": {
      "description": "one video (≤50MB). Passed alongside imageUrls it joins the album as one more item.",
      "type": "string"
    },
    "disablePreview": {
      "description": "suppress the link-preview card on a text-only post. Default is Telegram’s own behaviour (previews on).",
      "type": "boolean"
    },
    "silent": {
      "description": "deliver without a notification sound (Telegram’s disable_notification). This is NOT a visibility setting — the message is just as visible.",
      "type": "boolean"
    },
    "platformCover": {
      "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (Telegram’s in-chat video cover). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins.",
      "type": "boolean"
    }
  },
  "required": [
    "chatId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "how many recent updates to scan, 1–100 (default 100)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "pack": {
      "description": "the pack id to buy (e.g. pack-2k) — omit to list the available packs first",
      "type": "string"
    },
    "confirm": {
      "description": "set true to actually charge the saved card for `pack` (required for the one-click charge; ignored on the checkout-link path)",
      "type": "boolean"
    },
    "quote_token": {
      "description": "the quoteToken returned by the quote step — REQUIRED (with confirm:true) to charge; it binds the exact pack + price you quoted (10-minute validity) and makes a retried confirm idempotent",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "description": "one-line summary of the bug"
    },
    "details": {
      "type": "string",
      "description": "what you were doing, the tool + arguments you called, what you expected, and what actually happened (paste the exact error)"
    },
    "severity": {
      "description": "high = blocks the task or loses paid work; medium = wrong output but workable; low = cosmetic",
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ]
    }
  },
  "required": [
    "summary",
    "details"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "description": "one line: the capability you need"
    },
    "details": {
      "type": "string",
      "description": "what the user was actually trying to achieve, why the current tools couldn't do it, and what you'd expect the capability to do"
    }
  },
  "required": [
    "summary",
    "details"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "plan": {
      "description": "the plan id to move to (e.g. pro) — omit to list the available plans first",
      "type": "string"
    },
    "period": {
      "description": "billing cadence — monthly (default) or yearly (2 months free)",
      "type": "string",
      "enum": [
        "mo",
        "yr"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "true to turn auto-reload on, false to turn it off"
    },
    "thresholdCredits": {
      "description": "reload when the balance drops below this many credits",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "reloadCredits": {
      "description": "how many credits to add each reload — must match a credit pack size (see buy_credits)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "enabled"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "type": "string",
      "description": "brand id (e.g. default / p_xxx), its exact name from list_brands, or the profile id of a workspace shared with you"
    }
  },
  "required": [
    "brand"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "the brand / client name for the new workspace"
    },
    "activate": {
      "description": "switch this connection to the new brand (default true) — everything you do next scopes to it",
      "type": "boolean"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "type": "string",
      "description": "brand id or exact name from list_brands"
    },
    "confirm": {
      "description": "REQUIRED true — this destroys the whole workspace and cannot be undone",
      "type": "boolean"
    },
    "confirmName": {
      "description": "the workspace's EXACT name, required when it is not empty — copy it from the inventory this tool returned, after the user has agreed to it",
      "type": "string"
    },
    "confirmConnectors": {
      "description": "the number of connected accounts the inventory reported, required when there is at least one — the user must specifically agree to losing them, because reconnecting each needs a browser and no agent can do it",
      "type": "number"
    }
  },
  "required": [
    "brand"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "getUploadUrl": {
      "description": "ASK FOR A ONE-TIME UPLOAD URL instead of uploading now — use this whenever the file is on the user’s machine and you can run a shell or an HTTP request. Returns a uploadUrl you PUT the raw bytes to (any HTTP client), which answers with the durable Hermoso url. It beats `dataUri` for anything but a small image: a data: URI spends the whole file as tokens in this conversation. One file per url, and it expires.",
      "type": "boolean"
    },
    "url": {
      "description": "a PUBLIC http(s) URL Hermoso fetches server-side (private/internal addresses are refused, and every redirect hop is re-checked). Works on every surface including the hosted connector, and the bytes never cross this connection — prefer this whenever the file is reachable on the web.",
      "type": "string"
    },
    "dataUri": {
      "description": "base64 data: URI of the file bytes (data:<mime>;base64,<…>) — bytes travel over this connection, so keep it small",
      "type": "string"
    },
    "name": {
      "description": "original file name — helps pick the right extension",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "message": {
      "description": "post text / caption",
      "type": "string"
    },
    "imageUrl": {
      "description": "public https URL, a data: URI, or a Hermoso /generated path (upload_file gives you one for a local file)",
      "type": "string"
    },
    "videoUrl": {
      "description": "public https URL, data: URI, or /generated path — FB video post / IG Reel",
      "type": "string"
    },
    "productTags": {
      "description": "INSTAGRAM SHOPPING — make the post SHOPPABLE by tagging products from the brand’s own catalog; tapping a tag opens the product’s price sheet inside Instagram. Instagram only. ON A PHOTO each tag is {product_id, x, y}, where x and y are FRACTIONS of the image from 0.0 (left/top) to 1.0 (right/bottom) — 0.5,0.5 is the middle — and BOTH are required, max 20. ON A REEL it is {product_id} ALONE with no coordinates, max 30. ON A CAROUSEL it is an array PER SLIDE ([[{…}], [], [{…}]]) because Instagram tags each slide’s own container, max 5 per slide and 20 across the post. Ids come from search_instagram_shopping_products; call list_instagram_shopping_catalogs FIRST, because tagging needs an APPROVED Instagram Shop and without one this fails after the media is already uploaded. A tag whose product is not “approved” is stored and shown to nobody.",
      "type": "array",
      "items": {}
    },
    "imageUrls": {
      "description": "CAROUSEL — an ORDERED list of image (and, where the channel allows, video) URLs published as ONE post the viewer swipes through. THIS IS NOT “post several” — it is a single post with several slides, which is what a multi-slide creative (a listicle, a “1/6 · SWIPE” deck) actually needs; publishing only its first slide tells the viewer to swipe at something that cannot. The ORDER is the product. Limits per channel: Instagram 2–10 (images, videos or a mix), Threads 2–20 (mix allowed), Facebook 2+ (Meta publishes no documented maximum; Hermoso caps the upload fan-out at 30 and says so), LinkedIn company Pages 2–20 (images only), Pinterest 2–5 (images only), TikTok up to 35. One url here is simply an ordinary single post. Anything a channel cannot do is REFUSED with the real reason — nothing is ever quietly downgraded to one slide.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "idempotencyKey": {
      "description": "SAFE RETRIES. Publishing can take minutes (a video upload, a carousel of ten slides) and a transport can time out while the post SUCCEEDS — retrying blind is how the same thing gets posted twice. Pass any stable string here and a repeat of the SAME publish returns the ORIGINAL post id instead of posting again (24h). You do not have to: an identical publish is auto-recognised for 10 minutes anyway. If a call times out or errors ambiguously, CALL AGAIN WITH THE SAME KEY — that is the safe move, and it will either report the original post or publish it for the first time. It never posts twice.",
      "type": "string"
    },
    "allowDuplicate": {
      "description": "post it even though an identical post was just made or attempted. Only pass this when the user genuinely wants the same thing posted twice, or when you have LOOKED at the account and confirmed a timed-out attempt did not land.",
      "type": "boolean"
    },
    "async": {
      "description": "publish in the BACKGROUND and return a job id to poll with get_job, instead of waiting. USE THIS FOR VIDEO: a Facebook or Instagram video publish routinely outlives an agent transport, and a timeout on the synchronous path leaves you unable to tell whether the post is live. With async:true nothing can time out — the job reports the post id and url when it lands.",
      "type": "boolean"
    },
    "link": {
      "description": "a URL to attach (FB text post only)",
      "type": "string"
    },
    "collaborators": {
      "description": "INSTAGRAM COLLAB — up to 3 Instagram usernames invited to CO-AUTHOR this post. Once one accepts, the post appears on THEIR profile too, with both handles in the header and the likes and comments shared — it is how a brand reaches a creator’s audience without paying for placement, and it is the single most-asked thing a scheduler normally cannot do. Pass handles only (\"hermosoai\"), not profile links; a leading @ is fine. INSTAGRAM ONLY — Facebook and Threads have no collab post at all and are refused BY NAME rather than silently dropping the co-authors — and never on a Story. AN INVITE IS NOT A CO-POST: publishing SENDS a request the other account must accept in their Instagram notifications, and until they do the post is on this brand’s profile ALONE; they may also decline, and Instagram sends no notification either way. So never report the post as live on both accounts — read the invite status back out of the reply, and use instagram_collaborators later to find out whether they accepted.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "target": {
      "description": "default facebook; instagram -> the Page’s linked IG; threads -> the brand’s connected Threads account",
      "type": "string",
      "enum": [
        "facebook",
        "instagram",
        "threads"
      ]
    },
    "account": {
      "description": "WHICH Instagram account when target is instagram and the brand has several — Page-linked and Instagram Login accounts alike; an @username or id from list_connector_accounts(\"instagram\"). Several and none named is refused by name; omit when there is one.",
      "type": "string"
    },
    "scheduleAt": {
      "description": "FACEBOOK ONLY — schedule instead of posting now. ISO timestamp (2026-08-01T09:00:00Z) or unix seconds; must be 10 minutes to 30 days ahead. Facebook holds the post and publishes it at that time, so nothing has to stay running on our side. Instagram and Threads have NO scheduling in Meta’s API — passing this for them is refused rather than silently posted immediately.",
      "type": "string"
    },
    "locationId": {
      "description": "TAG A PLACE. THREADS: a place id from search_threads_locations. INSTAGRAM: the NUMERIC ID OF A FACEBOOK PAGE associated with that location, not a place name and not coordinates; a non-numeric value is refused rather than sent.",
      "type": "string"
    },
    "audience": {
      "description": "FACEBOOK PAGE POST ONLY — limit who can see this organic post to people in these places and/or over this age (Facebook allows 13, 15, 18, 21 or 25). Not on Instagram, Threads or a Facebook Reel (a vertical clip becomes a Reel): those are refused. Region and city keys come from the Meta ads location search.",
      "type": "object",
      "properties": {
        "countries": {
          "description": "two-letter codes, e.g. [\"CA\",\"US\"]",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "regions": {
          "description": "Meta location keys for regions/states",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "cities": {
          "description": "Meta location keys for cities",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "minAge": {
          "anyOf": [
            {
              "type": "number",
              "const": 13
            },
            {
              "type": "number",
              "const": 15
            },
            {
              "type": "number",
              "const": 18
            },
            {
              "type": "number",
              "const": 21
            },
            {
              "type": "number",
              "const": 25
            }
          ]
        }
      }
    },
    "place": {
      "description": "FACEBOOK — tag a location on the Page post. The NUMERIC ID OF THE FACEBOOK PAGE for that place, not a place name and not coordinates.",
      "type": "string"
    },
    "callToAction": {
      "description": "FACEBOOK — a real call-to-action BUTTON on the Page post. The types that open a destination (SHOP_NOW, LEARN_MORE, SIGN_UP, BUY_NOW, DOWNLOAD, OPEN_LINK, WATCH_MORE, BOOK_TRAVEL) need somewhere to go: the post’s own `link`, or `callToActionLink`. CALL_NOW, MESSAGE_PAGE, LIKE_PAGE and GET_DIRECTIONS act on the Page itself and take none.",
      "type": "string",
      "enum": [
        "BOOK_TRAVEL",
        "BUY_NOW",
        "CALL_NOW",
        "DOWNLOAD",
        "GET_DIRECTIONS",
        "LEARN_MORE",
        "LIKE_PAGE",
        "MESSAGE_PAGE",
        "NO_BUTTON",
        "OPEN_LINK",
        "SHOP_NOW",
        "SIGN_UP",
        "WATCH_MORE"
      ]
    },
    "callToActionLink": {
      "description": "FACEBOOK — where the button goes, when that is not the post’s own `link`.",
      "type": "string"
    },
    "linkName": {
      "description": "FACEBOOK — override the HEADLINE of the link preview. Without it the post shows whatever Open Graph title the destination carries, which on a bare landing page is often nothing. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager > Brand safety > Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain.",
      "type": "string"
    },
    "linkDescription": {
      "description": "FACEBOOK — override the DESCRIPTION of the link preview. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager > Brand safety > Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain.",
      "type": "string"
    },
    "linkPicture": {
      "description": "FACEBOOK — override the IMAGE of the link preview: a public http(s) url Facebook fetches itself. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager > Brand safety > Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain.",
      "type": "string"
    },
    "coverUrl": {
      "description": "INSTAGRAM REEL COVER — a public image url Instagram fetches and uses as the cover in the Reels tab. REELS ONLY, and the alternative to `thumbOffset`: passing both is refused, since they are two answers to the same question. Run a local file through upload_file first.",
      "type": "string"
    },
    "thumbOffset": {
      "description": "INSTAGRAM REEL COVER, the other way — which frame becomes the cover, in MILLISECONDS from the start of the video. REELS ONLY. Use it instead of `coverUrl` when the right cover is already a frame of the clip.",
      "type": "number"
    },
    "shareToFeed": {
      "description": "INSTAGRAM REEL — true puts the Reel in the Feed grid as well as the Reels tab. REELS ONLY. Left unset it follows Instagram’s own default; Hermoso does not flip it either way on the user’s behalf.",
      "type": "boolean"
    },
    "audioName": {
      "description": "INSTAGRAM REEL — the name of the Reel’s audio track, which is what viewers tap through to. REELS ONLY.",
      "type": "string"
    },
    "paidPartnership": {
      "description": "INSTAGRAM — the PAID PARTNERSHIP label. A COMPLIANCE DECLARATION, the same kind Hermoso already carries for TikTok and X: set it whenever the post is sponsored, gifted or otherwise paid for. Opt-in and never inferred — it is the poster’s own statement about their commercial relationship.",
      "type": "boolean"
    },
    "brandedContentSponsorIds": {
      "description": "INSTAGRAM — the numeric Instagram USER IDS of the brands behind that label (at most 2, and ids rather than @handles). Naming sponsors IS asking for the label, so setting these with `paidPartnership:false` is refused instead of publishing brand credits with no disclosure.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "trialReel": {
      "description": "INSTAGRAM TRIAL REEL — publish this Reel to NON-FOLLOWERS ONLY at first (Instagram allows trials only on accounts above its follower threshold — about 1,000 followers; an ineligible account is refused by name and nothing is posted), so a hook can be tested on a cold audience without spending it on the people who already follow the brand. Instagram then shows it to followers only if it graduates. MANUAL = the creator graduates it by hand in the Instagram app; SS_PERFORMANCE = Instagram graduates it automatically if it performs well. REELS ONLY and INSTAGRAM ONLY: an image, a carousel, a Facebook post or a Threads post is REFUSED BY NAME rather than quietly published as an ordinary post — a trial that silently goes to every follower is the exact opposite of what was asked for. Omit it for a normal Reel.",
      "type": "string",
      "enum": [
        "MANUAL",
        "SS_PERFORMANCE"
      ]
    },
    "story": {
      "description": "INSTAGRAM STORY — publish this as a 24-hour Story instead of a feed post. One image OR one video: Instagram has no carousel story, so a carousel is REFUSED BY NAME rather than quietly posted to the feed. A Story carries NO CAPTION (there is nowhere to show one), no collaborators, no product tags and no trialReel — passing any of those is refused by name and nothing is posted, because a story that silently drops the words is worse than one that never went. INSTAGRAM ONLY: a Facebook Page story is a different upload and is not built, so a Facebook channel with `story` set is refused rather than published to the feed.",
      "type": "boolean"
    },
    "aiGenerated": {
      "description": "INSTAGRAM / FACEBOOK REEL — Meta’s is_ai_generated self-disclosure. OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, media that came through upload_file or from an external URL (the user’s own photographs or footage) is NOT — a real photo must never carry Instagram’s “AI info” label. Pass true or false only to override: false strips the label from something Hermoso would otherwise declare, true declares a render the user uploaded themselves.",
      "type": "boolean"
    },
    "altText": {
      "description": "ACCESSIBILITY — the description screen readers announce, and what the platform otherwise auto-generates badly or not at all. Describe what is actually IN the picture, never the caption. ONE STRING describes the picture; on a CAROUSEL it describes EVERY slide. Pass an ARRAY of strings instead to describe each slide separately, aligned to the slide order — that is strictly better on a multi-slide post, because one sentence read out over six different pictures is wrong for five of them. More descriptions than pictures is refused rather than dropped. WHERE IT LANDS, per Meta’s own docs: INSTAGRAM image posts and the IMAGE slides of an Instagram carousel (up to 1000 characters; dropped rather than sent on a Reel or a video slide, which Meta do not support); FACEBOOK Page photos including every photo of an album, via alt_text_custom (Meta publish no length for it, so nothing is truncated); THREADS on a single-image or single-video post ONLY — Meta document no way to attach alt text to a Threads CAROUSEL slide, so a Threads carousel publishes undescribed and the reply says so rather than risking the whole post on a guess. (Meta’s AI disclosure defaults from PROVENANCE: a Hermoso render is declared is_ai_generated; media that came through upload_file or an external URL, i.e. the user’s own photos or footage, is NOT. Pass `aiGenerated` to force it either way.)",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "pageId": {
      "description": "target Page id (from list_meta_pages); omit = first Page",
      "type": "string"
    },
    "linkAttachment": {
      "description": "THREADS TEXT POSTS ONLY — a full http(s) URL rendered as a clickable link card. This is how a Threads post carries a destination at all; without it a link is just text. Meta allows at most 5 links per post and refuses a link attachment on a post that also carries an image or video, so Hermoso refuses that combination up front rather than letting Meta silently drop it.",
      "type": "string"
    },
    "replyControl": {
      "description": "THREADS ONLY — who may reply. Default is everyone.",
      "type": "string",
      "enum": [
        "everyone",
        "accounts_you_follow",
        "mentioned_only",
        "parent_post_author_only",
        "followers_only"
      ]
    },
    "quotePostId": {
      "description": "THREADS ONLY — the id of a post to QUOTE. A quote post is a distinct post type, not a formatting option.",
      "type": "string"
    },
    "topicTag": {
      "description": "THREADS ONLY — one topic tag for discovery, 1–50 characters. A leading # is stripped for you; Threads refuses \".\" and \"&\".",
      "type": "string"
    },
    "countryCodes": {
      "description": "THREADS ONLY — restrict the post to these ISO 3166-1 alpha-2 countries. Warning: This is an ALLOWLIST, so the post becomes INVISIBLE in every country not named — it narrows reach, it does not target.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "crossreshareToIg": {
      "description": "THREADS ONLY — ALSO share this Threads post to the linked Instagram account AS A STORY (not a feed post), in the same publish. NOT available on a Threads CAROUSEL, which is refused by name rather than silently dropped. THERE IS NO CONFIRMATION: Threads returns no field saying whether the Story was created, so report it as REQUESTED and tell the user to check their Instagram Stories — never that it is live.",
      "type": "boolean"
    },
    "crossreshareDarkMode": {
      "description": "THREADS ONLY — render that Instagram Story in dark mode. Only meaningful alongside crossreshareToIg; on its own it is refused rather than silently ignored, because a parameter that never reaches the wire must not look accepted.",
      "type": "boolean"
    },
    "platformCover": {
      "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (Instagram Reel: thumb_offset; Facebook video/Reel: an uploaded cover image) — and on Threads, which has no cover setting, a blank first frame is replaced on a copy sent to Threads only. true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "channels": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "facebook",
          "instagram",
          "threads",
          "tiktok",
          "youtube",
          "linkedin",
          "x",
          "pinterest",
          "google_business",
          "bluesky",
          "telegram"
        ]
      },
      "description": "one or more channels to post to at that time"
    },
    "at": {
      "description": "when to post — ISO timestamp (2026-08-01T09:00:00Z) or epoch milliseconds. Must be in the future, at most 365 days out. Give this OR useQueue, never both.",
      "type": "string"
    },
    "useQueue": {
      "description": "instead of naming a minute, drop this into the brand’s POSTING QUEUE: Hermoso takes the earliest of its saved posting times that is still free (skipping any slot another queued post already holds). This is the natural answer to “just queue it” / “post it at my next opening”. Mutually exclusive with `at` — passing both is refused rather than one being silently preferred. If the brand has no posting times set, or every slot for the next 90 days is taken, it is refused by name and nothing is scheduled.",
      "type": "boolean"
    },
    "timezone": {
      "description": "IANA zone for the queue, e.g. \"America/New_York\" — only meaningful with useQueue, and it overrides the brand’s saved zone for this one post. A saved slot of \"09:00\" is a WALL-CLOCK time, so the zone is what turns it into an instant; without either the brand’s saved zone or this, the queue resolves in UTC.",
      "type": "string"
    },
    "message": {
      "description": "the caption/text used for every channel unless overridden in captions",
      "type": "string"
    },
    "captions": {
      "description": "per-channel caption overrides, e.g. { \"instagram\": \"…\", \"threads\": \"…\" } — platforms want different lengths and hashtag conventions",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "accounts": {
      "description": "WHICH accounts of a multi-account channel to post to, e.g. { \"tiktok\": [\"@a\", \"@b\"] } or { \"tiktok\": \"all\" } — one row per account at fire time, each with its own result. Omit for channels with one account (several and none named is refused by name).",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "string",
            "const": "all"
          }
        ]
      }
    },
    "imageUrl": {
      "description": "a Hermoso render URL (a /generated path, or what upload_file returned), a data: URI, or a public https URL. NOTE: only Facebook/Instagram/Threads accept an arbitrary public URL — X, TikTok, YouTube, LinkedIn, Pinterest and Google Business re-host the bytes and REFUSE anything that is not a Hermoso render, so run an external file through upload_file first and schedule that url.",
      "type": "string"
    },
    "videoUrl": {
      "description": "a Hermoso render URL (a /generated path, or what upload_file returned), a data: URI, or a public https URL — required for youtube, and for tiktok unless you pass an imageUrl (TikTok takes a photo post too). Same origin rule as imageUrl: everything except Facebook/Instagram/Threads REFUSES a non-Hermoso URL, so pass external video through upload_file first.",
      "type": "string"
    },
    "imageUrls": {
      "description": "CAROUSEL — an ORDERED list of image URLs to publish as ONE swipeable post on every channel that supports it (Instagram 2–10, Threads 2–20, Facebook, LinkedIn company Pages 2–20, Pinterest 2–5, TikTok up to 35 as a photo post). Use this whenever the creative is a multi-slide deck: a scheduled post carrying only slide 1 of a “1/6 · SWIPE” set is a broken ad that nobody is watching when it fires. THE ORDER IS THE PRODUCT. A channel on this schedule that cannot do carousels — X, YouTube, Google Business Profile — is REFUSED NOW, with the reason, so you can drop it or give it its own single image; it is never quietly downgraded hours later.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "title": {
      "description": "PINTEREST / YOUTUBE — the headline, max 100 characters. Pinterest shows it in search and under the pin; YouTube requires one. Leave it out and Hermoso derives one from that channel’s caption (first sentence, cut on a word boundary, trailing hashtags dropped) — set a real one whenever the caption does not open with a usable headline.",
      "type": "string"
    },
    "description": {
      "description": "YOUTUBE: the video DESCRIPTION, max 5000 characters, carrying the links, the CTA and what YouTube search reads. Omit it and the caption is used.",
      "type": "string"
    },
    "tags": {
      "description": "YOUTUBE — up to 30 search tags for the video (plain words, no #).",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "thumbnailUrl": {
      "description": "YOUTUBE: the custom thumbnail, a Hermoso-hosted image (make_thumbnail, or upload_file for the user’s own). Omit it and a frame of the video is used; \"auto\" keeps YouTube’s pick.",
      "type": "string"
    },
    "replyControl": {
      "description": "THREADS ONLY — who may reply. Omit for Threads' own default (everyone).",
      "type": "string",
      "enum": [
        "everyone",
        "accounts_you_follow",
        "mentioned_only",
        "parent_post_author_only",
        "followers_only"
      ]
    },
    "quotePostId": {
      "description": "THREADS ONLY — the id of the Threads post this one quotes.",
      "type": "string"
    },
    "linkAttachment": {
      "description": "THREADS ONLY — a full http(s) URL rendered as a link card. This is the ONLY way a Threads post carries a destination, and Threads attaches it to TEXT-ONLY posts (a post with media cannot also carry a card).",
      "type": "string"
    },
    "topicTag": {
      "description": "THREADS ONLY — one topic tag for the post, without the leading #.",
      "type": "string"
    },
    "countryCodes": {
      "description": "THREADS ONLY — two-letter country codes to limit who can see the post. Omit to show it everywhere.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "crossreshareToIg": {
      "description": "THREADS ONLY — when this fires, ALSO share it to the linked Instagram account as a STORY. Refused on a Threads carousel. No confirmation exists that the Story was created, so the result says it was requested.",
      "type": "boolean"
    },
    "crossreshareDarkMode": {
      "description": "THREADS ONLY — render that Instagram Story in dark mode. Needs crossreshareToIg.",
      "type": "boolean"
    },
    "slideText": {
      "description": "PINTEREST CAROUSEL ONLY — per-slide title / description / link, aligned to slide order. Every other platform takes ONE caption for the whole carousel.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "link": {
            "type": "string"
          }
        }
      }
    },
    "altText": {
      "description": "ACCESSIBILITY — the screen-reader description of the attached image. ONE STRING describes the picture; on a CAROUSEL it describes EVERY slide. Pass an ARRAY of strings instead to describe each slide separately, aligned to the slide order — that is strictly better on a multi-slide post, because one sentence read out over six different pictures is wrong for five of them. More descriptions than pictures is refused rather than dropped. Write one whenever the post carries an image: describe what is IN the picture, never a repeat of the caption, which a screen reader already reads. CARRIED BY: X (max 1000, one per media), Pinterest (max 500 — PIN-LEVEL only, since its API has no per-item alt text, so slide 1’s description is used for the whole Pin and the result says the others were not sent), LinkedIn COMPANY PAGES (max 4086, one per slide), INSTAGRAM image posts and image slides (max 1000), FACEBOOK photos and albums, and BLUESKY, whose lexicon makes it REQUIRED on every image. The schedule is REFUSED if the LONGEST description exceeds the tightest of the channels on it, rather than truncated on the way out. NOT CARRIED, and none of these is a refusal — the post still publishes, just undescribed there, and the per-channel result says which: TikTok (its photo post has no alt field at any level), a THREADS CAROUSEL, an INSTAGRAM Reel or video slide, and a LinkedIn PERSONAL-profile post.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "link": {
      "description": "a link to attach (Facebook)",
      "type": "string"
    },
    "brandedContent": {
      "description": "TIKTOK — the PAID-PARTNERSHIP disclosure (TikTok’s brand_content_toggle): true when this post promotes a THIRD-PARTY business. It is a compliance declaration, not a preference — set it whenever the post is sponsored. TikTok only accepts branded content on a public or friends-only post, so it cannot ride a private/SELF_ONLY or draft TikTok item and the schedule is refused with the reason.",
      "type": "boolean"
    },
    "yourBrand": {
      "description": "TIKTOK — the OWN-BRAND disclosure (brand_organic_toggle): true when the post promotes the creator’s own business. TikTok asks for at least one of this and brandedContent once a post is commercial.",
      "type": "boolean"
    },
    "privacyLevel": {
      "description": "TIKTOK — WHICH PRIVACY LEVEL the post goes out at, in TikTok’s own vocabulary. TikTok requires the USER to choose this from the levels their own account allows: call tiktok_creator_info, show them the real options, and pass back the one they picked — never a default and never a guess, which TikTok refuses at init. Omit it and the post falls back to the coarse `visibility` (private -> SELF_ONLY, otherwise PUBLIC_TO_EVERYONE), which cannot express MUTUAL_FOLLOW_FRIENDS or FOLLOWER_OF_CREATOR at all. It must agree with the TikTok visibility (SELF_ONLY is the private one) and it is refused on a TikTok DRAFT, which carries no post info.",
      "type": "string",
      "enum": [
        "PUBLIC_TO_EVERYONE",
        "MUTUAL_FOLLOW_FRIENDS",
        "FOLLOWER_OF_CREATOR",
        "SELF_ONLY"
      ]
    },
    "commercialContent": {
      "description": "TIKTOK — the COMMERCIAL CONTENT DISCLOSURE toggle: true when the post promotes a brand, product or service at all. TikTok requires at least one of yourBrand / brandedContent alongside it, and a post declaring itself commercial without naming which kind is refused. Setting either disclosure already implies this, so it is only needed to be explicit.",
      "type": "boolean"
    },
    "disableComment": {
      "description": "TIKTOK — turn comments off on this post.",
      "type": "boolean"
    },
    "disableDuet": {
      "description": "TIKTOK VIDEO ONLY — block Duets. TikTok’s photo-post API has no Duets, so this is refused on a photo/slideshow item rather than silently dropped.",
      "type": "boolean"
    },
    "disableStitch": {
      "description": "TIKTOK VIDEO ONLY — block Stitches. Same photo-post rule as disableDuet.",
      "type": "boolean"
    },
    "coverTimestampMs": {
      "description": "TIKTOK VIDEO ONLY — which frame TikTok uses as the cover, in milliseconds from the start. Omit and Hermoso uses the video’s best frame (platformCover:true leaves it to TikTok, which uses the first frame).",
      "type": "number"
    },
    "topicType": {
      "description": "GOOGLE BUSINESS — the KIND of Post. STANDARD is the default; EVENT and OFFER both REQUIRE `event` (title + start date), and OFFER also takes `offer`.",
      "type": "string",
      "enum": [
        "STANDARD",
        "EVENT",
        "OFFER",
        "ALERT"
      ]
    },
    "actionType": {
      "description": "GOOGLE BUSINESS — the call-to-action button. Every button except CALL needs `link` (CALL dials the number on the listing and takes none). Google IGNORES the button link on an OFFER post — put the destination in offer.redeemOnlineUrl. Omit and a post carrying a link gets LEARN_MORE.",
      "type": "string",
      "enum": [
        "BOOK",
        "ORDER",
        "SHOP",
        "LEARN_MORE",
        "SIGN_UP",
        "CALL"
      ]
    },
    "event": {
      "description": "GOOGLE BUSINESS — required for an EVENT or OFFER post: {title, startDate:\"YYYY-MM-DD\", endDate, startTime:\"HH:MM\", endTime}. `title` is the EVENT’s headline, a different thing from the post `title` (which is the Pinterest/YouTube one). Google documents its TimeInterval as needing all four date/time parts to be valid, so send the times whenever you know them.",
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "startDate": {
          "type": "string"
        },
        "startTime": {
          "type": "string"
        },
        "endDate": {
          "type": "string"
        },
        "endTime": {
          "type": "string"
        }
      }
    },
    "offer": {
      "description": "GOOGLE BUSINESS — OFFER posts only: {couponCode, redeemOnlineUrl, termsConditions}. redeemOnlineUrl is where an offer actually sends people, since the button link is ignored on an Offer.",
      "type": "object",
      "properties": {
        "couponCode": {
          "type": "string"
        },
        "redeemOnlineUrl": {
          "type": "string"
        },
        "termsConditions": {
          "type": "string"
        }
      }
    },
    "thread": {
      "description": "X — publish a THREAD, one entry per post, each replying to the one before (at most 25). 280 characters per part without X Premium, up to 25,000 with it; nothing is truncated. It REPLACES the X caption: with a thread set, `message`/`captions.x` is not sent to X at all. A thread cannot carry a poll.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "poll": {
      "description": "X — attach a poll: {options:[\"…\",\"…\"], durationMinutes}. 2–4 options of at most 25 characters each; voting runs 5–10080 minutes (7 days), default 1440. X makes a poll MUTUALLY EXCLUSIVE with media, so an item carrying an image or video is refused — schedule the poll as its own X-only post.",
      "type": "object",
      "properties": {
        "options": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "durationMinutes": {
          "type": "number"
        }
      },
      "required": [
        "options"
      ]
    },
    "replySettings": {
      "description": "X — who may reply. Omit for everyone, which is the right default for a brand post.",
      "type": "string",
      "enum": [
        "following",
        "mentionedUsers",
        "subscribers",
        "verified"
      ]
    },
    "madeWithAi": {
      "description": "X — X’s AI-media label on this post. Opt-in: X treats it as the poster’s own claim about their media, so it is never set on the user’s behalf.",
      "type": "boolean"
    },
    "xQuotePostId": {
      "description": "X — the numeric id of an X post this one QUOTES: the last part of its URL. NAMED xQuotePostId, NOT quotePostId, because `quotePostId` on this same schedule belongs to THREADS. Billed at X’s higher LINK rate.",
      "type": "string"
    },
    "communityId": {
      "description": "X — publish into an X COMMUNITY instead of the main timeline: the number in the community’s own URL (x.com/i/communities/<id>). The connected account must be a MEMBER of it.",
      "type": "string"
    },
    "paidPartnership": {
      "description": "INSTAGRAM AND X — the PAID PARTNERSHIP label, a compliance declaration: set it when the post is sponsored, gifted or otherwise paid for. OPT-IN ONLY, never assume it on the user’s behalf. On Instagram, brandedContentSponsorIds names the brands behind it.",
      "type": "boolean"
    },
    "xArticle": {
      "description": "X: publish the X item as a long-form X ARTICLE. title is its headline, the X text (message or captions.x) its markdown body, the image its cover. Refused now if the markdown has formatting X cannot hold. X allows about 5 Articles a day; one that fires into that cap fails with the reset time and can be retried.",
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "headings": {
          "type": "string",
          "enum": [
            "blocks",
            "text"
          ]
        }
      },
      "required": [
        "title"
      ]
    },
    "collaborators": {
      "description": "INSTAGRAM — a COLLAB post: up to 3 Instagram usernames invited to CO-AUTHOR it, so it appears on their profile too once they accept, with both handles in the header and the engagement shared. Handles only (\"hermosoai\"); a leading @ is fine. Instagram must be one of the `channels` — asking for collaborators on a schedule Instagram is not on is REFUSED now rather than discovered when it fires, and the other channels in a mixed schedule simply publish without co-authors. THE INVITE IS SENT WHEN THE POST FIRES, not when you schedule it, and it is PENDING until the other account accepts in their notifications; check with instagram_collaborators afterwards rather than telling the user it is live on both profiles.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "audience": {
      "description": "FACEBOOK PAGE POST ONLY — limit who can see this organic post to people in these places and/or over this age (Facebook allows 13, 15, 18, 21 or 25). Not on Instagram, Threads or a Facebook Reel (a vertical clip becomes a Reel): those are refused. Region and city keys come from the Meta ads location search.",
      "type": "object",
      "properties": {
        "countries": {
          "description": "two-letter codes, e.g. [\"CA\",\"US\"]",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "regions": {
          "description": "Meta location keys for regions/states",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "cities": {
          "description": "Meta location keys for cities",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "minAge": {
          "anyOf": [
            {
              "type": "number",
              "const": 13
            },
            {
              "type": "number",
              "const": 15
            },
            {
              "type": "number",
              "const": 18
            },
            {
              "type": "number",
              "const": 21
            },
            {
              "type": "number",
              "const": 25
            }
          ]
        }
      }
    },
    "targetAudience": {
      "description": "LINKEDIN COMPANY PAGE POST ONLY — show the post only to Page followers matching these facets (URNs or bare numeric ids; search_linkedin_ads_targeting finds them). LinkedIn requires the matching audience to be over 300 followers and refuses a smaller one. Personal-profile posts cannot be targeted.",
      "type": "object",
      "properties": {
        "geoLocations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "industries": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "seniorities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "jobFunctions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "staffCountRanges": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "SIZE_1",
              "SIZE_2_TO_10",
              "SIZE_11_TO_50",
              "SIZE_51_TO_200",
              "SIZE_201_TO_500",
              "SIZE_501_TO_1000",
              "SIZE_1001_TO_5000",
              "SIZE_5001_TO_10000",
              "SIZE_10001_OR_MORE"
            ]
          }
        },
        "degrees": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "fieldsOfStudy": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "organizations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "place": {
      "description": "FACEBOOK — tag a location on the Page post. The NUMERIC ID OF THE FACEBOOK PAGE for that place, not a place name and not coordinates.",
      "type": "string"
    },
    "callToAction": {
      "description": "FACEBOOK — a real call-to-action BUTTON on the Page post. The types that open a destination (SHOP_NOW, LEARN_MORE, SIGN_UP, BUY_NOW, DOWNLOAD, OPEN_LINK, WATCH_MORE, BOOK_TRAVEL) need somewhere to go: the post’s own `link`, or `callToActionLink`. CALL_NOW, MESSAGE_PAGE, LIKE_PAGE and GET_DIRECTIONS act on the Page itself and take none.",
      "type": "string",
      "enum": [
        "BOOK_TRAVEL",
        "BUY_NOW",
        "CALL_NOW",
        "DOWNLOAD",
        "GET_DIRECTIONS",
        "LEARN_MORE",
        "LIKE_PAGE",
        "MESSAGE_PAGE",
        "NO_BUTTON",
        "OPEN_LINK",
        "SHOP_NOW",
        "SIGN_UP",
        "WATCH_MORE"
      ]
    },
    "callToActionLink": {
      "description": "FACEBOOK — where the button goes, when that is not the post’s own `link`.",
      "type": "string"
    },
    "linkName": {
      "description": "FACEBOOK — override the HEADLINE of the link preview. Without it the post shows whatever Open Graph title the destination carries, which on a bare landing page is often nothing. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager > Brand safety > Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain.",
      "type": "string"
    },
    "linkDescription": {
      "description": "FACEBOOK — override the DESCRIPTION of the link preview. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager > Brand safety > Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain.",
      "type": "string"
    },
    "linkPicture": {
      "description": "FACEBOOK — override the IMAGE of the link preview: a public http(s) url Facebook fetches itself. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager > Brand safety > Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain.",
      "type": "string"
    },
    "coverUrl": {
      "description": "INSTAGRAM REEL COVER — a public image url Instagram fetches and uses as the cover in the Reels tab. REELS ONLY, and the alternative to `thumbOffset`: passing both is refused, since they are two answers to the same question. Run a local file through upload_file first.",
      "type": "string"
    },
    "thumbOffset": {
      "description": "INSTAGRAM REEL COVER, the other way — which frame becomes the cover, in MILLISECONDS from the start of the video. REELS ONLY. Use it instead of `coverUrl` when the right cover is already a frame of the clip.",
      "type": "number"
    },
    "shareToFeed": {
      "description": "INSTAGRAM REEL — true puts the Reel in the Feed grid as well as the Reels tab. REELS ONLY. Left unset it follows Instagram’s own default; Hermoso does not flip it either way on the user’s behalf.",
      "type": "boolean"
    },
    "audioName": {
      "description": "INSTAGRAM REEL — the name of the Reel’s audio track, which is what viewers tap through to. REELS ONLY.",
      "type": "string"
    },
    "instagramLocationId": {
      "description": "INSTAGRAM — tag a place (called locationId on post_to_meta; locationId here is the Google Business listing). It is the NUMERIC ID OF A FACEBOOK PAGE associated with that location, not a place name and not coordinates; a non-numeric value is refused rather than sent.",
      "type": "string"
    },
    "brandedContentSponsorIds": {
      "description": "INSTAGRAM — the numeric Instagram USER IDS of the brands behind that label (at most 2, and ids rather than @handles). Naming sponsors IS asking for the label, so setting these with `paidPartnership:false` is refused instead of publishing brand credits with no disclosure.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "trialReel": {
      "description": "INSTAGRAM TRIAL REEL — publish this Reel to NON-FOLLOWERS ONLY at first (Instagram allows trials only on accounts above its follower threshold — about 1,000 followers; an ineligible account is refused by name and nothing is posted), so a hook can be tested on a cold audience without spending it on the people who already follow the brand; Instagram shows it to followers only if it graduates. MANUAL = the creator graduates it by hand in the Instagram app; SS_PERFORMANCE = Instagram graduates it automatically if it performs. REELS ONLY and INSTAGRAM ONLY: an image, a carousel, or a Facebook/Threads channel is REFUSED BY NAME rather than quietly published as an ordinary post — a trial that silently goes to every follower is the exact opposite of what was asked for, so Instagram must be one of the `channels` and the item must carry a video. Omit it for a normal Reel.",
      "type": "string",
      "enum": [
        "MANUAL",
        "SS_PERFORMANCE"
      ]
    },
    "story": {
      "description": "INSTAGRAM STORY — publish this as a 24-hour Story instead of a feed post. One image OR one video: Instagram has no carousel story, so a carousel is REFUSED BY NAME rather than quietly posted to the feed. A Story carries NO CAPTION (there is nowhere to show one), no collaborators, no product tags and no trialReel — passing any of those is refused by name and nothing is posted, because a story that silently drops the words is worse than one that never went. INSTAGRAM ONLY: a Facebook Page story is a different upload and is not built, so a Facebook channel with `story` set is refused rather than published to the feed.",
      "type": "boolean"
    },
    "aiGenerated": {
      "description": "INSTAGRAM / FACEBOOK REEL — Meta’s is_ai_generated self-disclosure. OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, media that came through upload_file or from an external URL (the user’s own photographs or footage) is NOT — a real photo must never carry Instagram’s “AI info” label. Pass true or false only to override: false strips the label from something Hermoso would otherwise declare, true declares a render the user uploaded themselves.",
      "type": "boolean"
    },
    "boardId": {
      "description": "PINTEREST — REQUIRED whenever pinterest is a channel: the board the Pin goes on, from list_pinterest_boards. The user picks it; a Pin on the wrong board is a public mistake. Scheduling pinterest without one is refused immediately.",
      "type": "string"
    },
    "chatId": {
      "description": "TELEGRAM — REQUIRED whenever telegram is a channel: WHICH chat, group or channel the bot posts to. A public channel’s @username (@hermosoai) or the numeric id (a group is negative; a supergroup or channel starts with -100). There is no default and there cannot be one — the Telegram Bot API publishes no method that lists a bot’s chats — so scheduling telegram without one is refused up front. list_telegram_chats finds ids for chats that have messaged the bot in the last 24 hours.",
      "type": "string"
    },
    "linkedinOrganizationId": {
      "description": "LINKEDIN — publish as a COMPANY PAGE instead of the connected personal profile. The organization id from list_linkedin_pages. Omit and it posts as the person: an unset id means the profile, never “probably the company”. A Page can also carry VIDEO, which a personal profile cannot.",
      "type": "string"
    },
    "pageId": {
      "description": "FACEBOOK / INSTAGRAM / THREADS — which connected Facebook Page (and its linked Instagram) publishes, from list_meta_pages. Needed when the brand has more than one Page connected; with several and no id the post is refused at fire time rather than sent from the wrong brand.",
      "type": "string"
    },
    "locationId": {
      "description": "GOOGLE BUSINESS PROFILE — which listing, e.g. 'locations/123' from list_business_locations. Needed when the account manages more than one storefront; it is never chosen for the user.",
      "type": "string"
    },
    "visibility": {
      "description": "how it should be published — DEFAULT 'public' (live). Only pass something else if the user explicitly asked to stage/hide it. Not every channel supports every value; an impossible combination is refused when you schedule it, with the reason.",
      "type": "string",
      "enum": [
        "public",
        "unlisted",
        "private",
        "draft"
      ]
    },
    "visibilityByChannel": {
      "description": "override visibility for one channel, e.g. { \"tiktok\": \"draft\" } to go live everywhere but stage TikTok for review",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "optimizeCopy": {
      "description": "RECOMMENDED when one caption goes to several channels: fit the shared caption to each channel’s own rules when you schedule it (the fitted caption is stored on the scheduled post, so what you scheduled is what publishes) wherever no per-channel caption was written. The angle and every claim stay the author’s; a channel with its own caption is left exactly as written. Off by default so nobody’s words are rewritten unasked.",
      "type": "boolean"
    },
    "platformCover": {
      "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover on every channel that allows one (Instagram, Facebook, TikTok direct posts, LinkedIn Pages, Pinterest, Telegram, YouTube) — and on X, Threads and Bluesky, which have none, a blank first frame is replaced on a copy sent there only. true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins.",
      "type": "boolean"
    }
  },
  "required": [
    "channels"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND to list — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED.",
      "type": "string"
    },
    "id": {
      "description": "one post id from this list: returns that post in full, every caption and setting included",
      "type": "string"
    },
    "channel": {
      "description": "only posts that include this channel, e.g. \"pinterest\" or \"x\"",
      "type": "string"
    },
    "upcoming": {
      "description": "how many queued posts to list, soonest first (default 25, max 200)",
      "type": "number"
    },
    "fired": {
      "description": "how many already-fired posts to list, most recent last (default 15, max 200)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND this post is in — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "the scheduled post id from list_scheduled"
    },
    "at": {
      "description": "the new time — ISO timestamp (2026-08-05T09:00:00Z) or epoch milliseconds. Must be in the future, at most 365 days out.",
      "type": "string"
    },
    "message": {
      "description": "replace the caption used for every channel that has no override",
      "type": "string"
    },
    "captions": {
      "description": "replaces the WHOLE per-channel caption map — send every override you want to keep, not just the new one",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "optimizeCopy": {
      "description": "fit the shared caption to each channel’s own rules when you schedule it (the fitted caption is stored on the scheduled post, so what you scheduled is what publishes) wherever no per-channel caption was written; a channel with its own caption is left exactly as written. Send false to switch it off on this item.",
      "type": "boolean"
    },
    "channels": {
      "description": "replaces the channel list",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "facebook",
          "instagram",
          "threads",
          "tiktok",
          "youtube",
          "linkedin",
          "x",
          "pinterest",
          "google_business",
          "bluesky",
          "telegram"
        ]
      }
    },
    "imageUrl": {
      "description": "swap the image; \"\" removes it",
      "type": "string"
    },
    "videoUrl": {
      "description": "swap the video; \"\" removes it",
      "type": "string"
    },
    "imageUrls": {
      "description": "replace the CAROUSEL slides, in order; an empty array [] drops the carousel and goes back to a single image. Omit to leave the slides exactly as they are. The edited item is re-checked against the same carousel rules the create passed, so adding a channel that cannot swipe is refused now rather than posting slide 1 later.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "title": {
      "description": "PINTEREST / YOUTUBE — replace the headline; \"\" clears it and goes back to deriving one from the caption",
      "type": "string"
    },
    "description": {
      "description": "YOUTUBE — replace the video description; \"\" clears it and the caption is used.",
      "type": "string"
    },
    "tags": {
      "description": "YOUTUBE — replaces the WHOLE tag list; an empty array [] clears the tags.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "thumbnailUrl": {
      "description": "YOUTUBE: replace the custom thumbnail; \"\" goes back to a frame of the video, \"auto\" to YouTube’s pick.",
      "type": "string"
    },
    "replyControl": {
      "description": "THREADS ONLY — who may reply.",
      "type": "string",
      "enum": [
        "everyone",
        "accounts_you_follow",
        "mentioned_only",
        "parent_post_author_only",
        "followers_only"
      ]
    },
    "quotePostId": {
      "description": "THREADS ONLY — the id of the Threads post this one quotes.",
      "type": "string"
    },
    "linkAttachment": {
      "description": "THREADS ONLY — a full http(s) URL rendered as a link card on a TEXT-ONLY post. The only way a Threads post carries a destination.",
      "type": "string"
    },
    "topicTag": {
      "description": "THREADS ONLY — one topic tag, without the leading #.",
      "type": "string"
    },
    "countryCodes": {
      "description": "THREADS ONLY — two-letter country codes limiting who can see the post.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "crossreshareToIg": {
      "description": "THREADS ONLY — also share to Instagram as a Story when it fires; false turns it off. Refused on a carousel.",
      "type": "boolean"
    },
    "crossreshareDarkMode": {
      "description": "THREADS ONLY — dark-mode that Instagram Story. Needs crossreshareToIg.",
      "type": "boolean"
    },
    "slideText": {
      "description": "PINTEREST CAROUSEL ONLY — per-slide title / description / link, aligned to slide order.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "link": {
            "type": "string"
          }
        }
      }
    },
    "privacyLevel": {
      "description": "TIKTOK — WHICH PRIVACY LEVEL the post goes out at, in TikTok’s own vocabulary. TikTok requires the USER to choose this from the levels their own account allows: call tiktok_creator_info, show them the real options, and pass back the one they picked — never a default and never a guess, which TikTok refuses at init. Omit it and the post falls back to the coarse `visibility` (private -> SELF_ONLY, otherwise PUBLIC_TO_EVERYONE), which cannot express MUTUAL_FOLLOW_FRIENDS or FOLLOWER_OF_CREATOR at all. It must agree with the TikTok visibility (SELF_ONLY is the private one) and it is refused on a TikTok DRAFT, which carries no post info.",
      "type": "string",
      "enum": [
        "PUBLIC_TO_EVERYONE",
        "MUTUAL_FOLLOW_FRIENDS",
        "FOLLOWER_OF_CREATOR",
        "SELF_ONLY"
      ]
    },
    "altText": {
      "description": "ACCESSIBILITY — replace the screen-reader description(s). A STRING describes every slide; an ARRAY describes them one at a time in slide order and REPLACES the whole list. \"\" clears it.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "link": {
      "type": "string"
    },
    "brandedContent": {
      "description": "TIKTOK — the paid-partnership disclosure; false turns it off.",
      "type": "boolean"
    },
    "yourBrand": {
      "description": "TIKTOK — the own-brand disclosure; false turns it off.",
      "type": "boolean"
    },
    "commercialContent": {
      "description": "TIKTOK — the COMMERCIAL CONTENT DISCLOSURE toggle: true when this post promotes a brand, product or service at all. TikTok requires at least one of yourBrand / brandedContent once it is on, and refuses a post that declares itself commercial without naming which kind. Either disclosure already implies it.",
      "type": "boolean"
    },
    "disableComment": {
      "description": "TIKTOK — comments off on this post.",
      "type": "boolean"
    },
    "disableDuet": {
      "description": "TIKTOK VIDEO ONLY — block Duets.",
      "type": "boolean"
    },
    "disableStitch": {
      "description": "TIKTOK VIDEO ONLY — block Stitches.",
      "type": "boolean"
    },
    "coverTimestampMs": {
      "description": "TIKTOK VIDEO ONLY — cover frame in milliseconds.",
      "type": "number"
    },
    "topicType": {
      "description": "GOOGLE BUSINESS — the kind of Post; EVENT and OFFER both require `event`.",
      "type": "string",
      "enum": [
        "STANDARD",
        "EVENT",
        "OFFER",
        "ALERT"
      ]
    },
    "actionType": {
      "description": "GOOGLE BUSINESS — the call-to-action button; \"\" clears it.",
      "type": "string",
      "enum": [
        "BOOK",
        "ORDER",
        "SHOP",
        "LEARN_MORE",
        "SIGN_UP",
        "CALL"
      ]
    },
    "event": {
      "description": "GOOGLE BUSINESS — replaces the whole event record {title, startDate, startTime, endDate, endTime}.",
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "startDate": {
          "type": "string"
        },
        "startTime": {
          "type": "string"
        },
        "endDate": {
          "type": "string"
        },
        "endTime": {
          "type": "string"
        }
      }
    },
    "offer": {
      "description": "GOOGLE BUSINESS — replaces the whole offer record {couponCode, redeemOnlineUrl, termsConditions}.",
      "type": "object",
      "properties": {
        "couponCode": {
          "type": "string"
        },
        "redeemOnlineUrl": {
          "type": "string"
        },
        "termsConditions": {
          "type": "string"
        }
      }
    },
    "thread": {
      "description": "X — replaces the WHOLE thread; an explicit [] drops back to a single post using the caption.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "poll": {
      "description": "X — replaces the poll; an empty options list removes it.",
      "type": "object",
      "properties": {
        "options": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "durationMinutes": {
          "type": "number"
        }
      },
      "required": [
        "options"
      ]
    },
    "replySettings": {
      "description": "X — who may reply; \"\" goes back to everyone.",
      "type": "string",
      "enum": [
        "following",
        "mentionedUsers",
        "subscribers",
        "verified"
      ]
    },
    "madeWithAi": {
      "description": "X — the AI-media label; false turns it off.",
      "type": "boolean"
    },
    "xQuotePostId": {
      "description": "X — the post this one QUOTES; an empty string removes the quote. Named apart from the Threads `quotePostId` on this same schedule.",
      "type": "string"
    },
    "communityId": {
      "description": "X — the community to publish into; an empty string goes back to the main timeline.",
      "type": "string"
    },
    "paidPartnership": {
      "description": "INSTAGRAM AND X — the paid-partnership label; false turns it off.",
      "type": "boolean"
    },
    "xArticle": {
      "description": "X: replaces the X Article (title, headings); {} makes it an ordinary X post again.",
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "headings": {
          "type": "string",
          "enum": [
            "blocks",
            "text"
          ]
        }
      }
    },
    "collaborators": {
      "description": "INSTAGRAM — replaces the WHOLE collab list (up to 3 usernames); an explicit [] removes the co-authors and the post goes out as an ordinary single-author post. Only takes effect if the post has not fired yet — an invite already sent cannot be withdrawn from here.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "trialReel": {
      "description": "INSTAGRAM — replaces the trial-reel setting on a queued Reel (MANUAL or SS_PERFORMANCE); an explicit \"\" turns the trial off and it goes out as an ordinary Reel. Only takes effect while the post is still queued — a Reel already published cannot be converted into a trial.",
      "type": "string",
      "enum": [
        "MANUAL",
        "SS_PERFORMANCE",
        ""
      ]
    },
    "story": {
      "description": "INSTAGRAM — true makes it a 24-hour Story, false an ordinary feed post. One image or one video, no carousel.",
      "type": "boolean"
    },
    "coverUrl": {
      "description": "INSTAGRAM REEL — replaces the cover image url; an empty string removes it.",
      "type": "string"
    },
    "thumbOffset": {
      "description": "INSTAGRAM REEL — replaces the cover frame, in milliseconds; 0 removes it. Never together with coverUrl.",
      "type": "number"
    },
    "shareToFeed": {
      "description": "INSTAGRAM REEL — whether the Reel also shows in the Feed grid.",
      "type": "boolean"
    },
    "audioName": {
      "description": "INSTAGRAM REEL — replaces the audio track name; an empty string removes it.",
      "type": "string"
    },
    "instagramLocationId": {
      "description": "INSTAGRAM — replaces the tagged place (the numeric id of its Facebook Page); an empty string removes it. Not locationId, which is the Google Business listing.",
      "type": "string"
    },
    "brandedContentSponsorIds": {
      "description": "INSTAGRAM — replaces the sponsor user ids behind the paid-partnership label (at most 2); [] removes them.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "place": {
      "description": "FACEBOOK — replaces the tagged place (the numeric id of its Facebook Page); an empty string removes it.",
      "type": "string"
    },
    "callToAction": {
      "description": "FACEBOOK — replaces the button on the Page post; \"\" removes it.",
      "type": "string",
      "enum": [
        "BOOK_TRAVEL",
        "BUY_NOW",
        "CALL_NOW",
        "DOWNLOAD",
        "GET_DIRECTIONS",
        "LEARN_MORE",
        "LIKE_PAGE",
        "MESSAGE_PAGE",
        "NO_BUTTON",
        "OPEN_LINK",
        "SHOP_NOW",
        "SIGN_UP",
        "WATCH_MORE",
        ""
      ]
    },
    "callToActionLink": {
      "description": "FACEBOOK — replaces where the button goes; an empty string falls back to the post link.",
      "type": "string"
    },
    "linkName": {
      "description": "FACEBOOK — replaces the link preview headline; an empty string removes the override.",
      "type": "string"
    },
    "linkDescription": {
      "description": "FACEBOOK — replaces the link preview description; an empty string removes the override.",
      "type": "string"
    },
    "linkPicture": {
      "description": "FACEBOOK — replaces the link preview image url; an empty string removes the override.",
      "type": "string"
    },
    "audience": {
      "description": "FACEBOOK — replaces who can see the Page post {countries, regions, cities, minAge}; {} removes the limit.",
      "type": "object",
      "properties": {
        "countries": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "regions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "cities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "minAge": {
          "type": "number"
        }
      }
    },
    "targetAudience": {
      "description": "LINKEDIN COMPANY PAGE — replaces who sees the post; {} removes the limit. The matching audience must be over 300 followers.",
      "type": "object",
      "properties": {
        "geoLocations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "industries": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "seniorities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "jobFunctions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "staffCountRanges": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "degrees": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "fieldsOfStudy": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "organizations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "aiGenerated": {
      "description": "INSTAGRAM / FACEBOOK REEL — Meta’s is_ai_generated self-disclosure. OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, media that came through upload_file or from an external URL (the user’s own photographs or footage) is NOT — a real photo must never carry Instagram’s “AI info” label. Pass true or false only to override: false strips the label from something Hermoso would otherwise declare, true declares a render the user uploaded themselves.",
      "type": "boolean"
    },
    "boardId": {
      "description": "PINTEREST — move the Pin to a different board (list_pinterest_boards)",
      "type": "string"
    },
    "chatId": {
      "description": "TELEGRAM — send it to a different chat, group or channel (@username or numeric id). It can be changed but never cleared: telegram cannot publish without one.",
      "type": "string"
    },
    "linkedinOrganizationId": {
      "description": "LINKEDIN — target a different company Page, or \"\" to post as the connected person instead",
      "type": "string"
    },
    "pageId": {
      "description": "FACEBOOK / INSTAGRAM / THREADS — publish from a different connected Page (list_meta_pages)",
      "type": "string"
    },
    "locationId": {
      "description": "GOOGLE BUSINESS — a different listing (list_business_locations)",
      "type": "string"
    },
    "visibility": {
      "description": "NOTE: changing this without also naming visibilityByChannel clears any per-channel overrides, so \"make it all draft\" is not a no-op",
      "type": "string",
      "enum": [
        "public",
        "unlisted",
        "private",
        "draft"
      ]
    },
    "visibilityByChannel": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "platformCover": {
      "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover on every channel that allows one — and on X, Threads and Bluesky, which have none, a blank first frame is replaced on a copy sent there only. true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins.",
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the scheduled post id from list_scheduled"
    },
    "brand": {
      "description": "WHICH BRAND this post is in — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND this post is in — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED.",
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "the scheduled post id from list_scheduled"
    },
    "channels": {
      "description": "retry only these channels (default: every channel that did not publish)",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "facebook",
          "instagram",
          "threads",
          "tiktok",
          "youtube",
          "linkedin",
          "x",
          "pinterest",
          "google_business",
          "bluesky",
          "telegram"
        ]
      }
    },
    "at": {
      "description": "hold the retry until a later time — ISO timestamp or epoch milliseconds. Leave it out to retry immediately, which is almost always what you want. A time you name here must be at least a minute from now, exactly like any other scheduled post.",
      "type": "string"
    },
    "allowDuplicate": {
      "description": "ONLY for a channel you have checked by hand and confirmed the post is genuinely NOT there. It bypasses the double-post protection and can publish a second public copy, so never set it to work around a refusal you have not investigated.",
      "type": "boolean"
    },
    "boardId": {
      "description": "CORRECT THE BOARD on retry — the Pinterest board the Pin goes on, from list_pinterest_boards. A Pin aimed at a board Pinterest refuses fails the same way on every retry until this is changed.",
      "type": "string"
    },
    "chatId": {
      "description": "CORRECT THE TELEGRAM DESTINATION on retry — the @username or numeric id of the chat. A post aimed at a chat the bot is not in fails every time it is retried until this changes.",
      "type": "string"
    },
    "pageId": {
      "description": "CORRECT THE PAGE on retry — which connected Facebook Page (and its linked Instagram/Threads) publishes, from list_meta_pages.",
      "type": "string"
    },
    "linkedinOrganizationId": {
      "description": "CORRECT THE LINKEDIN AUTHOR on retry — the company Page id from list_linkedin_pages. Set it to an empty string to fall back to the personal profile.",
      "type": "string"
    },
    "locationId": {
      "description": "CORRECT THE LISTING on retry — which Google Business Profile location, e.g. \"locations/123\" from list_business_locations.",
      "type": "string"
    },
    "message": {
      "description": "CORRECT THE CAPTION on retry — use this when the original was refused for length or content. Anything not named here is copied from the original post.",
      "type": "string"
    },
    "captions": {
      "description": "CORRECT ONE CHANNEL’S CAPTION on retry, e.g. { \"x\": \"...\" } when only that channel refused the text.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND this post is in — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED.",
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "the post to copy, from list_scheduled"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "at": {
      "description": "when the copy goes out — ISO timestamp or epoch milliseconds (default: an hour from now)",
      "type": "string"
    },
    "useQueue": {
      "description": "instead of naming a time, take the brand’s next free posting slot",
      "type": "boolean"
    },
    "timezone": {
      "description": "IANA zone for the queue, e.g. \"America/New_York\"",
      "type": "string"
    },
    "channels": {
      "description": "post the copy to these channels instead of the original’s",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "facebook",
          "instagram",
          "threads",
          "tiktok",
          "youtube",
          "linkedin",
          "x",
          "pinterest",
          "google_business",
          "bluesky",
          "telegram"
        ]
      }
    },
    "message": {
      "description": "a different caption for the copy",
      "type": "string"
    },
    "captions": {
      "description": "per-channel caption overrides for the copy",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "imageUrl": {
      "type": "string"
    },
    "videoUrl": {
      "type": "string"
    },
    "imageUrls": {
      "description": "CAROUSEL — an ORDERED list of image URLs published as ONE swipeable post",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "title": {
      "type": "string"
    },
    "link": {
      "type": "string"
    },
    "boardId": {
      "description": "PINTEREST — the board for the copy (list_pinterest_boards)",
      "type": "string"
    },
    "chatId": {
      "description": "TELEGRAM — which chat, group or channel the copy goes to (@username or numeric id)",
      "type": "string"
    },
    "linkedinOrganizationId": {
      "description": "LINKEDIN — publish the copy as this company Page (list_linkedin_pages)",
      "type": "string"
    },
    "pageId": {
      "description": "FACEBOOK / INSTAGRAM / THREADS — which connected Page (list_meta_pages)",
      "type": "string"
    },
    "locationId": {
      "description": "GOOGLE BUSINESS — which listing (list_business_locations)",
      "type": "string"
    },
    "visibility": {
      "type": "string",
      "enum": [
        "public",
        "unlisted",
        "private",
        "draft"
      ]
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "enabled": {
      "description": "on/off. false PAUSES it: the recurring job is deleted and nothing new is queued. Already-queued posts are untouched.",
      "type": "boolean"
    },
    "dryRun": {
      "description": "true (the default) = plan and preview only, queue nothing. Set false ONLY after a human has read a preview.",
      "type": "boolean"
    },
    "daysAhead": {
      "description": "how far ahead to keep the queue full, 1–30 (default 7)",
      "type": "number"
    },
    "postsPerDay": {
      "description": "cap the posts per day BELOW the number of posting times. 0 (default) = use every posting time, which is where \"3 a day\" comes from. To post MORE per day, add posting times instead.",
      "type": "number"
    },
    "assetCooldownDays": {
      "description": "how long before a Library render may be posted again (default 30). It never repeats one inside this window — it queues fewer posts and says so.",
      "type": "number"
    },
    "maxImagesPerDay": {
      "description": "how many NEW images a day it may render when the Library runs dry. 0 (default) = none, spend nothing.",
      "type": "number"
    },
    "maxVideosPerDay": {
      "description": "how many NEW videos a day it may render. 0 (default) = none. Video is the expensive one — hundreds of credits each.",
      "type": "number"
    },
    "maxCreditsPerDay": {
      "description": "a hard credit ceiling per day, checked BEFORE any render starts. It binds independently of the counts above.",
      "type": "number"
    },
    "channels": {
      "description": "restrict it to these channels. Omit (or send an empty list) to use every connected channel that can carry each post.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "facebook",
          "instagram",
          "threads",
          "tiktok",
          "youtube",
          "linkedin",
          "x",
          "pinterest",
          "google_business",
          "bluesky",
          "telegram"
        ]
      }
    },
    "boardId": {
      "description": "PINTEREST — which board Pins go on (list_pinterest_boards). Without one, Pinterest is skipped: a Pin on the wrong board is a public mistake, so it is never guessed.",
      "type": "string"
    },
    "chatId": {
      "description": "TELEGRAM — which chat, group or channel posts go to (@username or numeric id). Without one, telegram is skipped: there is no default chat and posting to the wrong one is a public mistake.",
      "type": "string"
    },
    "linkedinOrganizationId": {
      "description": "LINKEDIN — which company Page to post as (list_linkedin_pages). A single shared Page is used automatically; a Page that is not shared with this brand is ignored rather than failing the whole post.",
      "type": "string"
    },
    "pageId": {
      "description": "FACEBOOK / INSTAGRAM / THREADS — which connected Page to publish from (list_meta_pages). Omit for the brand’s only Page.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "dryRun": {
      "description": "default TRUE (preview only). false actually queues the posts.",
      "type": "boolean"
    },
    "force": {
      "description": "plan even while the refill is switched off — useful for showing someone what it would do before they turn it on. Combined with dryRun:false it still respects a stored dryRun.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "text": {
      "type": "string",
      "description": "the post text"
    },
    "imageUrl": {
      "description": "a Hermoso-hosted image URL to attach (≤12MB) — a Hermoso render, or ANY file of the user’s own put through upload_file first. An arbitrary external host is refused (we fetch the bytes ourselves).",
      "type": "string"
    },
    "imageUrls": {
      "description": "A CAROUSEL IS NOT AVAILABLE ON A PERSONAL PROFILE — LinkedIn's organic multi-image post publishes from a COMPANY PAGE. Passing several here is refused by name rather than posting slide 1; use post_to_linkedin_page instead.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "idempotencyKey": {
      "description": "SAFE RETRIES. Publishing can take minutes (a video upload, a carousel of ten slides) and a transport can time out while the post SUCCEEDS — retrying blind is how the same thing gets posted twice. Pass any stable string here and a repeat of the SAME publish returns the ORIGINAL post id instead of posting again (24h). You do not have to: an identical publish is auto-recognised for 10 minutes anyway. If a call times out or errors ambiguously, CALL AGAIN WITH THE SAME KEY — that is the safe move, and it will either report the original post or publish it for the first time. It never posts twice.",
      "type": "string"
    },
    "allowDuplicate": {
      "description": "post it even though an identical post was just made or attempted. Only pass this when the user genuinely wants the same thing posted twice, or when you have LOOKED at the account and confirmed a timed-out attempt did not land.",
      "type": "boolean"
    },
    "visibility": {
      "description": "default PUBLIC",
      "type": "string",
      "enum": [
        "PUBLIC",
        "CONNECTIONS"
      ]
    }
  },
  "required": [
    "text"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "account": {
      "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one x account connected (several and none named is refused by name, never guessed); omit when there is one.",
      "type": "string"
    },
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "text": {
      "description": "the post text. 280 characters without X Premium, up to 25,000 with it — write the full thing, it is never truncated. Use this OR thread, not both.",
      "type": "string"
    },
    "thread": {
      "description": "a thread: each string is one post, published in order, each replying to the previous. Max 25. Each part follows the same length rule as `text`, and on an X Premium account ONE long post is usually both better reading and cheaper than a thread.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "mediaUrl": {
      "description": "a Hermoso render (image or video) to attach to the first post — pass its served URL, or an upload_file url for external media",
      "type": "string"
    },
    "videoUrl": {
      "description": "alias of mediaUrl for a VIDEO — same as passing it as mediaUrl",
      "type": "string"
    },
    "imageUrl": {
      "description": "alias of mediaUrl for an IMAGE — same as passing it as mediaUrl",
      "type": "string"
    },
    "mediaUrls": {
      "description": "UP TO FOUR Hermoso-hosted media attached to ONE post — X’s own schema caps media_ids at 4. X renders them as a GRID: every image visible at once, nothing to swipe to. That is NOT a carousel, and a numbered \"1/6 · SWIPE\" slide deck must still not be sent here — it would publish as a grid and the \"swipe\" instruction would make no sense. Order decides the layout. On a thread the media rides the FIRST post; give each later part its own post to attach more. Mutually exclusive with mediaUrl, and more than 4 is refused before anything is uploaded.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "altText": {
      "description": "accessibility description of the attached media, max 1000 characters — write one whenever you attach a render. Costs a small extra amount: X bills one metadata write PER media. With SEVERAL media, pass an ARRAY aligned to their order — X attaches alt text per media id, and a single string describes only the FIRST one (X renders up to four media as a GRID, not a carousel, so one sentence would be wrong for the other three).",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "poll": {
      "description": "run a poll on the post. X does not allow a poll and media on the same post, and a poll cannot ride on a thread.",
      "type": "object",
      "properties": {
        "options": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "2-4 choices, max 25 characters each"
        },
        "durationMinutes": {
          "description": "5 to 10080 minutes (7 days); default 1440 = one day",
          "type": "number"
        }
      },
      "required": [
        "options"
      ]
    },
    "replySettings": {
      "description": "restrict who can reply — omit for everyone, which is the right default for a brand post",
      "type": "string",
      "enum": [
        "following",
        "mentionedUsers",
        "subscribers",
        "verified"
      ]
    },
    "replyToId": {
      "description": "numeric id of an existing X post to reply to. X ONLY ACCEPTS AN API REPLY TO A POST THAT MENTIONS THIS ACCOUNT OR THAT THIS ACCOUNT WROTE (X policy since Feb 2026, every tier below Enterprise): a cold reply under a stranger's post is refused by X with \"You can only reply to or quote posts where you are mentioned or are the author\" and nothing is posted. Reply to those from x.com itself; use this for replies in your own threads and to people who tagged you.",
      "type": "string"
    },
    "quotePostId": {
      "description": "numeric id of a post to QUOTE — X renders the quoted post inside yours. This is NOT replyToId: a reply sits under the original in its thread, a quote stands alone on your own timeline with the original embedded, which is the one you want for commentary. X makes a quote mutually exclusive with media and with a poll (their own schema), and a quote is billed at the higher LINK rate because X appends the quoted post’s t.co URL whatever your text says. Same X rule as replyToId: a quote of a post that does not mention this account is refused by X.",
      "type": "string"
    },
    "communityId": {
      "description": "publish into an X COMMUNITY instead of the main timeline — the number in the community’s own URL (x.com/i/communities/<id>). The connected account must be a MEMBER of it; X answers a non-member and a non-existent id with the same refusal and does not separate them.",
      "type": "string"
    },
    "paidPartnership": {
      "description": "label the post a PAID PARTNERSHIP on X — the same disclosure Hermoso already ships for TikTok. OPT-IN ONLY: set it when the post is sponsored, gifted or otherwise paid for, and never assume it on the user’s behalf.",
      "type": "boolean"
    },
    "platformCover": {
      "description": "VIDEO COVER. X has no cover setting and shows the video’s FIRST frame, so by default Hermoso checks it and, only when that frame is blank (a template ad’s empty opening card), sends X a copy with the first frame replaced by the video’s best frame. Your Library file is never changed. true = send the file exactly as it is.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "title": {
      "type": "string",
      "description": "the Article title — X requires one and refuses a draft without it. This is what shows on the timeline card."
    },
    "body": {
      "type": "string",
      "description": "the article body, as markdown or plain prose. Markdown headings, lists, quotes, links, emphasis, ``` code fences and | pipe | tables | are all converted to X’s own Article structure."
    },
    "coverImageUrl": {
      "description": "optional cover picture for the Article — a Hermoso render URL or an upload_file url. Must be a STILL image; X Article covers are not videos.",
      "type": "string"
    },
    "headings": {
      "description": "how headings are rendered. “blocks” (default) uses X’s own heading block types for # and ## headings; ### and deeper become bold lines, because X Articles refuse a third-level heading (the reply says so). “text” renders every heading as a BOLD standalone paragraph instead: the words survive and the heading structure does not, and the reply says so.",
      "type": "string",
      "enum": [
        "blocks",
        "text"
      ]
    },
    "allowLossy": {
      "description": "publish even though part of the source cannot be represented on X, rendering those parts as plain text. OFF by default and it should usually stay off — silently publishing a user’s copy with formatting missing is worse than refusing and telling them.",
      "type": "boolean"
    },
    "publish": {
      "description": "default true. Pass false to save it as a DRAFT in the account’s X Articles composer instead — nothing becomes public, the user can review and publish it from X, and it does not spend one of the five daily publishes.",
      "type": "boolean"
    }
  },
  "required": [
    "title",
    "body"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "privacy": {
      "description": "filter by board privacy; default is everything the connection can see",
      "type": "string",
      "enum": [
        "ALL",
        "PUBLIC",
        "PROTECTED",
        "SECRET"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "account": {
      "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one pinterest account connected (several and none named is refused by name, never guessed); omit when there is one.",
      "type": "string"
    },
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "boardId": {
      "type": "string",
      "description": "numeric board id from list_pinterest_boards — the user picks it, never guess"
    },
    "imageUrl": {
      "description": "a Hermoso render image URL (or an upload_file url)",
      "type": "string"
    },
    "videoUrl": {
      "description": "a Hermoso render video URL — takes 1–2 minutes to ingest",
      "type": "string"
    },
    "imageUrls": {
      "description": "CAROUSEL — an ORDERED list of image (and, where the channel allows, video) URLs published as ONE post the viewer swipes through. THIS IS NOT “post several” — it is a single post with several slides, which is what a multi-slide creative (a listicle, a “1/6 · SWIPE” deck) actually needs; publishing only its first slide tells the viewer to swipe at something that cannot. The ORDER is the product. Limits per channel: Instagram 2–10 (images, videos or a mix), Threads 2–20 (mix allowed), Facebook 2+ (Meta publishes no documented maximum; Hermoso caps the upload fan-out at 30 and says so), LinkedIn company Pages 2–20 (images only), Pinterest 2–5 (images only), TikTok up to 35. One url here is simply an ordinary single post. Anything a channel cannot do is REFUSED with the real reason — nothing is ever quietly downgraded to one slide.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "idempotencyKey": {
      "description": "SAFE RETRIES. Publishing can take minutes (a video upload, a carousel of ten slides) and a transport can time out while the post SUCCEEDS — retrying blind is how the same thing gets posted twice. Pass any stable string here and a repeat of the SAME publish returns the ORIGINAL post id instead of posting again (24h). You do not have to: an identical publish is auto-recognised for 10 minutes anyway. If a call times out or errors ambiguously, CALL AGAIN WITH THE SAME KEY — that is the safe move, and it will either report the original post or publish it for the first time. It never posts twice.",
      "type": "string"
    },
    "allowDuplicate": {
      "description": "post it even though an identical post was just made or attempted. Only pass this when the user genuinely wants the same thing posted twice, or when you have LOOKED at the account and confirmed a timed-out attempt did not land.",
      "type": "boolean"
    },
    "title": {
      "description": "Pin title, max 100 characters",
      "type": "string"
    },
    "description": {
      "description": "Pin description, max 800 characters — this is what Pinterest search reads",
      "type": "string"
    },
    "link": {
      "description": "destination URL the Pin clicks through to",
      "type": "string"
    },
    "altText": {
      "description": "accessibility alt text, max 500 characters. PIN-LEVEL: Pinterest’s API has no per-item alt text at all, so on a CAROUSEL the FIRST description is used for the whole Pin and the reply states that the others were not sent.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "slideText": {
      "description": "PINTEREST CAROUSEL ONLY — per-slide title, description and destination LINK, one object per slide in slide order. This is the ONLY genuine per-slide caption on any channel Hermoso publishes to: slide 4 can send people to the product ON slide 4, where every other platform gives a carousel one shared caption. Omit any field to leave it unset; the Pin’s own title/description/link still describe the Pin as a whole. Pinterest publishes no length limit on these, so nothing is truncated. More entries than slides is refused rather than dropped.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "link": {
            "type": "string"
          }
        }
      }
    },
    "coverImageUrl": {
      "description": "video Pins only — a render to use as the cover frame",
      "type": "string"
    },
    "boardSectionId": {
      "description": "optional section within the board",
      "type": "string"
    },
    "platformCover": {
      "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (on Pinterest the frame rides as the cover image). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins.",
      "type": "boolean"
    }
  },
  "required": [
    "boardId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "summary": {
      "description": "the body text of the Post",
      "type": "string"
    },
    "locationId": {
      "description": "which listing, e.g. 'locations/123' from list_business_locations — only needed when the account manages more than one",
      "type": "string"
    },
    "imageUrl": {
      "description": "a Hermoso render image URL (or an upload_file url) to show on the Post",
      "type": "string"
    },
    "topicType": {
      "description": "default STANDARD",
      "type": "string",
      "enum": [
        "STANDARD",
        "EVENT",
        "OFFER",
        "ALERT"
      ]
    },
    "actionType": {
      "description": "the button on the Post",
      "type": "string",
      "enum": [
        "BOOK",
        "ORDER",
        "SHOP",
        "LEARN_MORE",
        "SIGN_UP",
        "CALL"
      ]
    },
    "link": {
      "description": "the URL the button opens — not for CALL, and ignored on an OFFER",
      "type": "string"
    },
    "title": {
      "description": "headline — REQUIRED for EVENT and OFFER",
      "type": "string"
    },
    "startDate": {
      "description": "YYYY-MM-DD — REQUIRED for EVENT and OFFER",
      "type": "string"
    },
    "endDate": {
      "description": "YYYY-MM-DD, defaults to startDate",
      "type": "string"
    },
    "couponCode": {
      "description": "OFFER only",
      "type": "string"
    },
    "redeemOnlineUrl": {
      "description": "OFFER only — this is the link Google actually uses on an offer",
      "type": "string"
    },
    "termsConditions": {
      "description": "OFFER only",
      "type": "string"
    },
    "languageCode": {
      "description": "BCP-47 language of the Post, default 'en'",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "account": {
      "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one youtube account connected (several and none named is refused by name, never guessed); omit when there is one.",
      "type": "string"
    },
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "videoUrl": {
      "type": "string",
      "description": "the video to post — a Hermoso render URL or an upload_file url"
    },
    "title": {
      "description": "REQUIRED in practice — the headline every search result and the Shorts feed shows (≤100 chars); an upload with no title is refused",
      "type": "string"
    },
    "description": {
      "description": "REQUIRED in practice — what the video shows, a line about the brand, a link and a few #hashtags (≤5000 chars); YouTube search, suggested videos and the Shorts feed rank on it, so an upload with no description (and no caption) is refused",
      "type": "string"
    },
    "tags": {
      "description": "up to 30 tags",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "thumbnailUrl": {
      "description": "the custom thumbnail: a Hermoso-hosted image (make_thumbnail, or upload_file for the user’s own). Omit it and a representative frame of the video is set, free; \"auto\" keeps YouTube’s pick. Custom thumbnails need a verified channel.",
      "type": "string"
    },
    "privacy": {
      "description": "default unlisted (anyone-with-link, ad-ready); public = live + searchable on the channel (confirm first); private = eyes-only (cannot run as an ad)",
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ]
    },
    "categoryId": {
      "description": "YouTube category id, NUMERIC — default \"22\" (People & Blogs), which is wrong for most ads. 1 Film & Animation · 2 Autos & Vehicles · 10 Music · 15 Pets & Animals · 17 Sports · 19 Travel & Events · 20 Gaming · 22 People & Blogs · 23 Comedy · 24 Entertainment · 25 News & Politics · 26 Howto & Style · 27 Education · 28 Science & Technology · 29 Nonprofits & Activism. The assignable set is region-specific, so the value is forwarded as given and YouTube has the last word.",
      "type": "string"
    },
    "publishAt": {
      "description": "SCHEDULE the publish — ISO 8601, e.g. \"2026-09-01T15:00:00Z\", and it must be in the future. YouTube only allows this on a PRIVATE video and makes it PUBLIC at that moment, so pass privacy:\"private\" (or leave privacy unset) — asking for a scheduled \"unlisted\" or \"public\" post is refused rather than half-honoured.",
      "type": "string"
    },
    "notifySubscribers": {
      "description": "THE DEFAULT FOLLOWS PRIVACY. privacy:\"public\" NOTIFIES the channel's subscribers — that is YouTube's own default and normally what someone publishing publicly wants. privacy:\"unlisted\" and \"private\" do NOT: the video is not on the channel, so announcing it is nonsense, and a blast to somebody's whole subscriber list cannot be undone. A scheduled publish (publishAt) is PRIVATE at upload, so it does not notify either — pass true to announce one. An explicit value ALWAYS wins in both directions: true announces an unlisted/private upload, false publishes publicly and quietly. The reply reports which way it went and why.",
      "type": "boolean"
    },
    "aiGenerated": {
      "description": "YouTube’s “altered or synthetic content” declaration (containsSyntheticMedia). OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, a video the user uploaded through upload_file or from an external URL is NOT — real footage must not carry the label. true/false overrides.",
      "type": "boolean"
    },
    "platformCover": {
      "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (YouTube custom thumbnail; the same as thumbnailUrl:\"auto\" when true). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins.",
      "type": "boolean"
    }
  },
  "required": [
    "videoUrl"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "account": {
      "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one tiktok account connected (several and none named is refused by name, never guessed); omit when there is one.",
      "type": "string"
    },
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "videoUrl": {
      "description": "the video to post — a Hermoso render URL or an upload_file url. Omit for a photo post.",
      "type": "string"
    },
    "imageUrls": {
      "description": "a PHOTO POST: 1–35 image URLs in slide order. One url = a single-image photo post. Do not combine with videoUrl.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "coverIndex": {
      "description": "photo posts: which slide is the cover, 0-based. Default 0 (the first slide).",
      "type": "number"
    },
    "destination": {
      "description": "\"post\" = live on the profile now (needs privacy + an explicit user yes); \"draft\" = to TikTok for the user to review and post themselves. Default \"draft\".",
      "type": "string",
      "enum": [
        "post",
        "draft"
      ]
    },
    "title": {
      "description": "the caption — hashtags go here (video ≤2200 chars, photo post ≤4000)",
      "type": "string"
    },
    "photoTitle": {
      "description": "photo posts only: a short title above the caption (≤90 chars). Defaults to the caption’s first line.",
      "type": "string"
    },
    "privacy": {
      "description": "REQUIRED for destination:\"post\", for photos and video alike. Must be one the creator actually allows — read them from tiktok_creator_info, never guess.",
      "type": "string",
      "enum": [
        "PUBLIC_TO_EVERYONE",
        "MUTUAL_FOLLOW_FRIENDS",
        "FOLLOWER_OF_CREATOR",
        "SELF_ONLY"
      ]
    },
    "disableComment": {
      "type": "boolean"
    },
    "disableDuet": {
      "description": "video only — TikTok has no duet on a photo post",
      "type": "boolean"
    },
    "disableStitch": {
      "description": "video only — TikTok has no stitch on a photo post",
      "type": "boolean"
    },
    "autoAddMusic": {
      "description": "photo posts only: let TikTok add a recommended track (default true — a silent slideshow reads as broken)",
      "type": "boolean"
    },
    "coverTimestampMs": {
      "description": "video only: which frame to use as the cover, in ms",
      "type": "number"
    },
    "aiGenerated": {
      "description": "TikTok’s is_aigc AI-generated-content label (video posts). OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, a video that came through upload_file or an external URL (the user’s own footage) is NOT. true/false overrides.",
      "type": "boolean"
    },
    "brandedContent": {
      "description": "discloses a paid partnership — cannot be combined with SELF_ONLY privacy",
      "type": "boolean"
    },
    "yourBrand": {
      "description": "discloses that this promotes the creator’s own brand",
      "type": "boolean"
    },
    "platformCover": {
      "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (TikTok video_cover_timestamp_ms, on a direct post — a draft takes no cover, you pick it in the TikTok app). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "string",
      "description": "gid://shopify/Product/… from list_shopify_products"
    },
    "imageUrl": {
      "type": "string",
      "description": "any public https image URL — a Hermoso render works, and so does ANY file of your own brought in with upload_file"
    },
    "alt": {
      "description": "alt text for accessibility and SEO; defaults to a generic credit",
      "type": "string"
    }
  },
  "required": [
    "productId",
    "imageUrl"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against.",
      "type": "string"
    },
    "hook": {
      "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works.",
      "type": "string"
    },
    "subject": {
      "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group.",
      "type": "string"
    },
    "recipe": {
      "description": "the post's FORMAT id, e.g. \"slideshow\" or \"imessage_chat\" — post_performance groups by it, so reuse one id per format",
      "type": "string"
    },
    "ideaId": {
      "description": "short id of the content-plan idea this post came from",
      "type": "string"
    },
    "organizationId": {
      "description": "numeric Page id from list_linkedin_pages",
      "type": "string"
    },
    "text": {
      "type": "string",
      "description": "the post text"
    },
    "linkUrl": {
      "description": "publish a LINK POST — LinkedIn renders a real preview card for this URL instead of leaving a bare link in the text. Mutually exclusive with imageUrl / videoUrl / imageUrls: LinkedIn’s content field is a union, so combining them is refused by name rather than one being dropped.",
      "type": "string"
    },
    "linkTitle": {
      "description": "the headline ON the preview card. LINKEDIN NEVER SCRAPES THE PAGE — their Posts API disables URL scraping for API partners outright — so if you do not pass this the card renders UNLABELLED. Fetch the page’s own title and pass it.",
      "type": "string"
    },
    "linkDescription": {
      "description": "the sub-line on the preview card. Same rule as linkTitle: absent means blank, because LinkedIn will not fetch it.",
      "type": "string"
    },
    "linkThumbnailUrl": {
      "description": "a Hermoso-hosted image used as the card’s picture (uploaded to LinkedIn for you). Without it the card has no image.",
      "type": "string"
    },
    "imageUrl": {
      "description": "a Hermoso-hosted image URL — a render (list_library), or ANY image of the user’s own passed through upload_file first. An arbitrary external host is refused.",
      "type": "string"
    },
    "videoUrl": {
      "description": "a Hermoso-hosted video URL — a render, or the user’s own footage via upload_file. LinkedIn processes it before publishing, which takes a minute.",
      "type": "string"
    },
    "imageUrls": {
      "description": "CAROUSEL — an ORDERED list of image (and, where the channel allows, video) URLs published as ONE post the viewer swipes through. THIS IS NOT “post several” — it is a single post with several slides, which is what a multi-slide creative (a listicle, a “1/6 · SWIPE” deck) actually needs; publishing only its first slide tells the viewer to swipe at something that cannot. The ORDER is the product. Limits per channel: Instagram 2–10 (images, videos or a mix), Threads 2–20 (mix allowed), Facebook 2+ (Meta publishes no documented maximum; Hermoso caps the upload fan-out at 30 and says so), LinkedIn company Pages 2–20 (images only), Pinterest 2–5 (images only), TikTok up to 35. One url here is simply an ordinary single post. Anything a channel cannot do is REFUSED with the real reason — nothing is ever quietly downgraded to one slide.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "idempotencyKey": {
      "description": "SAFE RETRIES. Publishing can take minutes (a video upload, a carousel of ten slides) and a transport can time out while the post SUCCEEDS — retrying blind is how the same thing gets posted twice. Pass any stable string here and a repeat of the SAME publish returns the ORIGINAL post id instead of posting again (24h). You do not have to: an identical publish is auto-recognised for 10 minutes anyway. If a call times out or errors ambiguously, CALL AGAIN WITH THE SAME KEY — that is the safe move, and it will either report the original post or publish it for the first time. It never posts twice.",
      "type": "string"
    },
    "allowDuplicate": {
      "description": "post it even though an identical post was just made or attempted. Only pass this when the user genuinely wants the same thing posted twice, or when you have LOOKED at the account and confirmed a timed-out attempt did not land.",
      "type": "boolean"
    },
    "altText": {
      "description": "accessibility alt text (max 4086 characters, ~120 recommended). A STRING describes every image; an ARRAY describes each slide of a multi-image post separately, in slide order — LinkedIn stores altText per image, and their own sample request carries a different one on each. Not available on a PERSONAL-profile post: LinkedIn’s member posting API has no alt-text field at all.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "title": {
      "description": "video title",
      "type": "string"
    },
    "captionsSrt": {
      "description": "CLOSED CAPTIONS for a videoUrl post — the SubRip (.srt) CONTENT itself, cue numbers and `00:00:00,000 --> 00:00:02,000` timing lines included, NOT a URL and NOT the plain script (a file with no timings is refused, because LinkedIn would accept it and then silently never show it). Most of LinkedIn is watched with the sound off, so an uncaptioned video is one most of the feed never hears. LinkedIn allows ONE caption file per video and ENGLISH ONLY; it can be attached only WHILE the video is uploaded, never added to a published post; and it is processed asynchronously, so the reply confirms it was UPLOADED and never that it is visible yet. Requires videoUrl — passing it on an image, carousel or link post is refused by name.",
      "type": "string"
    },
    "videoThumbnailUrl": {
      "description": "the COVER IMAGE for a videoUrl post — a Hermoso-hosted image (a render, or any picture of the user’s via upload_file). Without it LinkedIn adds a system-generated thumbnail, which on an ad is usually whatever the first frame happens to be. Like captions this can only be set WHILE the video is uploaded, never afterwards. Requires videoUrl. This is NOT linkThumbnailUrl, which is the picture on a link-preview card.",
      "type": "string"
    },
    "visibility": {
      "description": "default PUBLIC",
      "type": "string",
      "enum": [
        "PUBLIC",
        "CONNECTIONS"
      ]
    },
    "targetAudience": {
      "description": "LINKEDIN COMPANY PAGE POST ONLY — show the post only to Page followers matching these facets (URNs or bare numeric ids; search_linkedin_ads_targeting finds them). LinkedIn requires the matching audience to be over 300 followers and refuses a smaller one. Personal-profile posts cannot be targeted.",
      "type": "object",
      "properties": {
        "geoLocations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "industries": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "seniorities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "jobFunctions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "staffCountRanges": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "SIZE_1",
              "SIZE_2_TO_10",
              "SIZE_11_TO_50",
              "SIZE_51_TO_200",
              "SIZE_201_TO_500",
              "SIZE_501_TO_1000",
              "SIZE_1001_TO_5000",
              "SIZE_5001_TO_10000",
              "SIZE_10001_OR_MORE"
            ]
          }
        },
        "degrees": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "fieldsOfStudy": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "organizations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "platformCover": {
      "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (LinkedIn’s video thumbnail upload). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins.",
      "type": "boolean"
    }
  },
  "required": [
    "text"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "pageId": {
      "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared",
      "type": "string"
    },
    "adAccountId": {
      "description": "read forms owned by an AD ACCOUNT instead of a Page",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "pageId": {
      "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared",
      "type": "string"
    },
    "adAccountId": {
      "description": "read forms owned by an AD ACCOUNT instead of a Page",
      "type": "string"
    },
    "formId": {
      "description": "only this form (from list_linkedin_lead_forms)",
      "type": "string"
    },
    "formVersion": {
      "description": "default 1",
      "type": "number"
    },
    "since": {
      "description": "ISO date or epoch milliseconds",
      "type": "string"
    },
    "until": {
      "type": "string"
    },
    "testLeadsOnly": {
      "description": "true returns ONLY test submissions",
      "type": "boolean"
    },
    "leadType": {
      "description": "defaults by owner: SPONSORED for an ad account, COMPANY (organic Page form) for a Page; EVENT for event forms. LinkedIn refuses SPONSORED on a Page owner",
      "type": "string",
      "enum": [
        "SPONSORED",
        "COMPANY",
        "EVENT",
        "ORGANIZATION_PRODUCT"
      ]
    },
    "limit": {
      "description": "per page, max 100",
      "type": "number"
    },
    "start": {
      "description": "offset for the next page",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "leadId": {
      "type": "string"
    },
    "pageId": {
      "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared",
      "type": "string"
    },
    "adAccountId": {
      "description": "read forms owned by an AD ACCOUNT instead of a Page",
      "type": "string"
    }
  },
  "required": [
    "leadId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "forwardTo": {
      "description": "optional public HTTPS URL Hermoso relays each lead event to (a CRM, Zapier, Make)",
      "type": "string"
    },
    "pageId": {
      "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared",
      "type": "string"
    },
    "adAccountId": {
      "description": "read forms owned by an AD ACCOUNT instead of a Page",
      "type": "string"
    },
    "leadType": {
      "description": "defaults by owner: SPONSORED for an ad account, COMPANY for a Page",
      "type": "string",
      "enum": [
        "SPONSORED",
        "COMPANY",
        "EVENT",
        "ORGANIZATION_PRODUCT"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "pageId": {
      "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared",
      "type": "string"
    },
    "adAccountId": {
      "description": "read forms owned by an AD ACCOUNT instead of a Page",
      "type": "string"
    },
    "leadType": {
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "subscriptionId": {
      "type": "string"
    },
    "pageId": {
      "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared",
      "type": "string"
    },
    "adAccountId": {
      "description": "read forms owned by an AD ACCOUNT instead of a Page",
      "type": "string"
    }
  },
  "required": [
    "subscriptionId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "url": {
      "description": "a single Hermoso render URL to save",
      "type": "string"
    },
    "urls": {
      "description": "several render URLs (up to 20) to save in one call",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "folder": {
      "description": "Drive folder name to save into (created if new)",
      "type": "string"
    },
    "name": {
      "description": "file name (single save)",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "drive",
        "onedrive"
      ],
      "description": "which cloud — `drive` is Google Drive, `onedrive` is Microsoft OneDrive"
    },
    "folderId": {
      "description": "the folder to import, from list_drive_files / list_onedrive_files (onlyFolders:true). Omit for the root of the drive.",
      "type": "string"
    },
    "limit": {
      "description": "how many files to bring across in this call (default 10, max 25). Anything over the limit is listed as skipped so you know what is left.",
      "type": "number"
    }
  },
  "required": [
    "provider"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "description": "only files whose name contains this",
      "type": "string"
    },
    "folderId": {
      "description": "list the contents of this folder id",
      "type": "string"
    },
    "onlyFolders": {
      "description": "list folders only",
      "type": "boolean"
    },
    "pageSize": {
      "description": "rows per page (1–200, default 50)",
      "type": "number"
    },
    "pageToken": {
      "description": "cursor from a previous call",
      "type": "string"
    },
    "includeTrashed": {
      "description": "include trashed files (default false)",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fileId": {
      "type": "string",
      "description": "the Drive file id (from list_drive_files)"
    }
  },
  "required": [
    "fileId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fileId": {
      "type": "string",
      "description": "the Drive file id"
    },
    "name": {
      "description": "new name",
      "type": "string"
    },
    "moveToFolderId": {
      "description": "folder id to move the file into (from create_drive_folder / list_drive_files)",
      "type": "string"
    },
    "removeFromFolderId": {
      "description": "the old parent folder id to remove (when moving)",
      "type": "string"
    },
    "trash": {
      "description": "true -> move to Trash; false -> restore from Trash",
      "type": "boolean"
    }
  },
  "required": [
    "fileId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fileId": {
      "type": "string",
      "description": "the Drive file id"
    },
    "permanent": {
      "description": "true = delete forever; default trashes (recoverable)",
      "type": "boolean"
    },
    "confirm": {
      "description": "REQUIRED true",
      "type": "boolean"
    }
  },
  "required": [
    "fileId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "folder name"
    },
    "parentId": {
      "description": "parent folder id for a nested folder (default: Drive root)",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "title": {
      "description": "spreadsheet title",
      "type": "string"
    },
    "rows": {
      "description": "rows to write — array of row arrays; first row = headers",
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            }
          ]
        }
      }
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "spreadsheetId": {
      "type": "string",
      "description": "the spreadsheet id from create_sheet"
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            }
          ]
        }
      },
      "description": "rows to append — array of row arrays"
    },
    "range": {
      "description": "range to append at (default A1 / first sheet)",
      "type": "string"
    }
  },
  "required": [
    "spreadsheetId",
    "rows"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "spreadsheetId": {
      "description": "the spreadsheet id (from create_sheet)",
      "type": "string"
    },
    "sheetUrl": {
      "description": "a Google Sheets URL to read — the spreadsheet id is extracted from it",
      "type": "string"
    },
    "range": {
      "description": "A1 range, e.g. \"A1:D50\" (default A1:Z1000)",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "collection": {
      "description": "the swipefile collection to export, by name or id (default: the first collection)",
      "type": "string"
    },
    "title": {
      "description": "deck title (default: the collection name)",
      "type": "string"
    },
    "limit": {
      "description": "max ads to include, 1-60 (default 30)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "title": {
      "description": "document title",
      "type": "string"
    },
    "text": {
      "description": "body text to insert",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "documentId": {
      "type": "string",
      "description": "the document id from create_doc"
    },
    "text": {
      "type": "string",
      "description": "text to append at the end of the doc"
    }
  },
  "required": [
    "documentId",
    "text"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "documentId": {
      "description": "the document id (from create_doc)",
      "type": "string"
    },
    "docUrl": {
      "description": "a Google Docs URL to read — the document id is extracted from it",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "spreadsheetId": {
      "description": "the spreadsheet id (from create_sheet, or list_drive_files for one the user picked)",
      "type": "string"
    },
    "sheetUrl": {
      "description": "a Google Sheets URL — the id is extracted from it",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "spreadsheetId": {
      "type": "string"
    },
    "sheetUrl": {
      "type": "string"
    },
    "range": {
      "description": "A1 range or anchor cell, e.g. \"B2:C5\", \"B2\", or \"Q3 Report!B2\" (default A1)",
      "type": "string"
    },
    "values": {
      "description": "array of row arrays to write",
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            }
          ]
        }
      }
    },
    "updates": {
      "description": "write SEVERAL disjoint ranges in one call, instead of range+values",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "range": {
            "type": "string"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "boolean"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "valueInputOption": {
      "description": "USER_ENTERED (default) parses formulas, dates and numbers the way typing them would; RAW stores every value as literal text",
      "type": "string",
      "enum": [
        "USER_ENTERED",
        "RAW"
      ]
    },
    "confirm": {
      "description": "required only when the target range already holds values",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "spreadsheetId": {
      "type": "string"
    },
    "sheetUrl": {
      "type": "string"
    },
    "range": {
      "type": "string",
      "description": "the range to clear, e.g. \"A2:D50\" or \"Sheet1!A2:D50\""
    },
    "confirm": {
      "type": "boolean"
    },
    "confirmCells": {
      "description": "echo back the filled-cell count the unconfirmed call reported",
      "type": "number"
    }
  },
  "required": [
    "range"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "spreadsheetId": {
      "type": "string"
    },
    "sheetUrl": {
      "type": "string"
    },
    "action": {
      "type": "string",
      "enum": [
        "add",
        "rename",
        "delete"
      ]
    },
    "tab": {
      "description": "which tab — its title or numeric sheetId (rename / delete)",
      "type": "string"
    },
    "title": {
      "description": "the name for the new tab (action:\"add\")",
      "type": "string"
    },
    "newTitle": {
      "description": "what to rename the tab to (action:\"rename\")",
      "type": "string"
    },
    "confirm": {
      "type": "boolean"
    },
    "confirmCells": {
      "type": "number"
    }
  },
  "required": [
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "spreadsheetId": {
      "type": "string"
    },
    "sheetUrl": {
      "type": "string"
    },
    "tab": {
      "description": "tab title or numeric sheetId (default: the first tab)",
      "type": "string"
    },
    "boldHeader": {
      "type": "boolean"
    },
    "freezeRows": {
      "description": "how many top rows to freeze (default 1, 0 = none)",
      "type": "number"
    },
    "autoResize": {
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "documentId": {
      "description": "the document id (from create_doc, or list_drive_files for one the user picked)",
      "type": "string"
    },
    "docUrl": {
      "description": "a Google Docs URL — the id is extracted from it",
      "type": "string"
    },
    "replacements": {
      "description": "find/replace pairs, applied in order",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "find": {
            "type": "string"
          },
          "replace": {
            "type": "string"
          },
          "matchCase": {
            "type": "boolean"
          }
        },
        "required": [
          "find"
        ]
      }
    },
    "rewrite": {
      "description": "replace the WHOLE body with this text (\"\" empties the doc)",
      "type": "string"
    },
    "confirm": {
      "type": "boolean"
    },
    "confirmCells": {
      "description": "echo back the character count the unconfirmed call reported (rewrite only)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "url": {
      "description": "a single Hermoso render URL to save",
      "type": "string"
    },
    "urls": {
      "description": "several render URLs (up to 20) to save in one call",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "folder": {
      "description": "OneDrive folder name to save into (created if new)",
      "type": "string"
    },
    "name": {
      "description": "file name (single save)",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "description": "search — only items whose name matches this",
      "type": "string"
    },
    "folderId": {
      "description": "list the contents of this folder id",
      "type": "string"
    },
    "onlyFolders": {
      "description": "list folders only",
      "type": "boolean"
    },
    "pageSize": {
      "description": "rows per page (1–200, default 50)",
      "type": "number"
    },
    "pageToken": {
      "description": "cursor from a previous call",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fileId": {
      "type": "string",
      "description": "the OneDrive item id (from list_onedrive_files)"
    }
  },
  "required": [
    "fileId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fileId": {
      "type": "string",
      "description": "the OneDrive item id"
    },
    "name": {
      "description": "new name",
      "type": "string"
    },
    "moveToFolderId": {
      "description": "folder id to move the item into (from create_onedrive_folder / list_onedrive_files)",
      "type": "string"
    }
  },
  "required": [
    "fileId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fileId": {
      "type": "string",
      "description": "the OneDrive item id"
    },
    "confirm": {
      "description": "REQUIRED true",
      "type": "boolean"
    }
  },
  "required": [
    "fileId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fileId": {
      "type": "string",
      "description": "the OneDrive item id, from list_onedrive_files"
    },
    "format": {
      "description": "default pdf",
      "type": "string",
      "enum": [
        "pdf",
        "jpg"
      ]
    },
    "width": {
      "description": "REQUIRED for jpg — output width in pixels",
      "type": "number"
    },
    "height": {
      "description": "REQUIRED for jpg — output height in pixels",
      "type": "number"
    }
  },
  "required": [
    "fileId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "folder name"
    },
    "parentId": {
      "description": "parent folder id for a nested folder (default: OneDrive root)",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "brand": {
      "description": "brand name, or a brand profile object {name,domain,category,palette,products,…}. OMIT to use the workspace’s SAVED brand + memory automatically (see get_brand); use draft_brand to onboard a new one",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {},
          "additionalProperties": {}
        }
      ]
    },
    "product": {
      "type": "string",
      "description": "what to advertise + any angle/offer the user specified"
    },
    "format": {
      "description": "'image', 'video', or 'auto' when unspecified",
      "type": "string",
      "enum": [
        "auto",
        "image",
        "video"
      ]
    },
    "durationSeconds": {
      "description": "VIDEO ONLY — the total spot length the user explicitly asked for, in seconds, copied verbatim (30 for \"a 30 second ad\"). The planner authors the storyboard TO it: the scenes’ seconds sum to it and the script is word-budgeted for it. Supported range 4–180; anything outside is CLAMPED to it (the reply says so). A length that fits ONE clip of the render model renders as a single continuous pass; anything longer is STITCHED from acts filled to that model’s clip maximum with the remainder last (on a 15s-clip model, 40 -> 15+15+10 and 17 -> 13+4) — never time-compressed. The maximum is the model’s own: 15s on most, 30s on the longest-clip model, so a 30s ad can be one unbroken take rather than two acts. Omit when the user named no length; do NOT pass a guess, an omitted value keeps the recipe-aware default.",
      "type": "number"
    },
    "hook": {
      "description": "force the VISUAL scroll-stop mechanic the opening beat is built on — a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"macro_asmr\"). Omit to let the planner pick. A hook that cannot be delivered in this brief is DROPPED with the reason rather than rendered wrongly — an on-screen-text hook on an authentic/UGC ad is the one that bites, because that register carries zero on-screen text.",
      "type": "string"
    },
    "setting": {
      "description": "force the WHERE — a setting id from list_hooks (e.g. \"kitchen\", \"gym\", or a surreal one like \"volcano_rim\" / \"airplane_wing\", which are played 100% straight and never acknowledged). Omit for a neutral setting.",
      "type": "string"
    },
    "recipe": {
      "description": "a recipe id from hermoso_capabilities to force an archetype",
      "type": "string"
    },
    "reference": {
      "description": "a reference to clone: an ad-library link (Facebook Ad Library, LinkedIn Ad Library, Google Ads Transparency — its real copy/advertiser are fetched) OR a VIDEO link — a TikTok, Instagram Reel, Facebook video, X post, YouTube Short/video or a direct video file — which is WATCHED first (frames + voiceover/on-screen-text transcript) so the concept keeps its hook, structure and pacing. To remake one video for this brand at its own length, clone_video is the direct tool",
      "type": "string"
    },
    "language": {
      "description": "output language for the ad copy (e.g. Spanish) — default English",
      "type": "string"
    },
    "draft": {
      "description": "ONLY after a video refusal that offered a light draft: the {model, durationSeconds} it named. The plan is then authored to that length and priced on that model. Never invent one — a video the account cannot cover is refused BEFORE planning with the three options (image / add credits / this draft when one fits), and the user chooses.",
      "type": "object",
      "properties": {
        "model": {
          "type": "string"
        },
        "durationSeconds": {
          "type": "number"
        }
      },
      "required": [
        "model",
        "durationSeconds"
      ]
    }
  },
  "required": [
    "product"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "the video to clone — a TikTok / Instagram Reel / Facebook / X / YouTube link, or a direct https video file URL"
    },
    "product": {
      "description": "what the new ad sells, plus any angle or offer; omit to use the saved brand's product",
      "type": "string"
    },
    "changes": {
      "description": "what to change or keep from the original, in the user's words (e.g. \"same hook but in a gym\", \"keep the jump cut, older creator\")",
      "type": "string"
    },
    "brand": {
      "description": "brand name or profile object; OMIT to use the workspace's saved brand (see get_brand)",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {},
          "additionalProperties": {}
        }
      ]
    },
    "durationSeconds": {
      "description": "override the length in seconds; omit to match the original",
      "type": "number"
    },
    "language": {
      "description": "language for the new ad's script and copy — default English",
      "type": "string"
    }
  },
  "required": [
    "url"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "the full image prompt — subject, composition, lighting, and any on-image ad text. ON A POSE MODEL (product-in-hand / try-on) THIS IS EXTRA DIRECTION AND IT IS OPTIONAL — leave it out and the pose is built for you. If you do write one, DESCRIBE THE POSE (\"she holds the bottle upright in her right hand at chest height, label to camera\"); do NOT phrase it as a swap (\"replace the mug with the bottle\"), which is REFUSED for free, because the product then comes out the size of whatever it replaced — a 30ml bottle rendered mug-sized in testing."
    },
    "refImages": {
      "description": "local file paths or URLs of product/logo references to composite in. ON THE POSE MODELS — any row hermoso_capabilities marks `needsRefs` with a `refsMax`, such as putting your product in someone’s hands or a virtual try-on — THE ORDER IS THE CONTRACT AND IT IS NOT A COMPOSITE: refImages[0] is the PERSON photo, and the rest (up to `refsMax` minus one) are the product or garment photos. Reversed, you get the product wearing the person. A 4th product is dropped and the reply says so. A real person’s photo confirms their likeness consent.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "useBrand": {
      "description": "default true: with no refImages, the server hydrates the SAVED brand’s product/logo references so the output lands on-brand; pass false for a pure prompt-only render",
      "type": "boolean"
    },
    "raw": {
      "description": "RAW MODEL ACCESS: run the caller’s prompt on the named model with no Hermoso adjustments at all — the prompt reaches the provider byte-identical (no hex-to-colour-name rewrite, no prepended fidelity preamble) and NO saved-brand product photos are attached, so the model you name is the model that renders. Use it to drive the raw catalog; leave it off for an on-brand ad. Billing, the durable Library landing and per-model validation are unchanged.",
      "type": "boolean"
    },
    "aspectRatio": {
      "description": "e.g. '1:1', '9:16', '16:9', '4:5'. Each model draws its own list (hermoso_capabilities prints it per model, e.g. Nano Banana 2 goes to 1:8 and 8:1); a ratio the chosen model cannot draw is refused before anything is charged",
      "type": "string"
    },
    "model": {
      "description": "image model id from hermoso_capabilities. A model whose `refs.mode` is \"edit\" there (gpt-image-2.5) takes your refImages on ITS OWN editor, up to its `refs.max`, instead of the default compositor",
      "type": "string"
    },
    "imageSize": {
      "description": "pixel-size preset for models that support it: 1K/2K, and 4K on the models hermoso_capabilities lists with a 4K imageSize price (a 4K ask on any other model is refused, free) — omit for the default",
      "type": "string"
    },
    "mask": {
      "description": "MASKED EDIT — change ONE region of an image and keep the rest: a local path or URL of a mask image for refImages[0] (the image being edited). Either convention works and the reply says which it read: TRANSPARENT pixels = change, or, on a mask with no transparency, WHITE = change and black = keep. Any size; it is scaled to the image. The mask GUIDES the edit rather than stencilling it: the new content can blend a little past its edge. Runs on the model hermoso_capabilities marks `refs.mask` (gpt-image-2.5): leave `model` empty or name that one — any other named model is refused, free. Needs refImages; the result keeps the source image's own frame, so aspectRatio is not applied.",
      "type": "string"
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "the image to edit: URL, Library item URL, upload_file URL or local path"
    },
    "instruction": {
      "type": "string",
      "description": "the change to make, in plain words (pass the user’s own words for a removal or plain photo edit)"
    },
    "removal": {
      "description": "true when the edit REMOVES text, branding, a logo, a watermark, a person or an object, so the brand name and logo are not re-added",
      "type": "boolean"
    },
    "mask": {
      "description": "optional mask image (URL or local path) marking the region to change: transparent = change, or white = change on an opaque mask",
      "type": "string"
    }
  },
  "required": [
    "image",
    "instruction"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "the finished static ad: URL, Library item URL, upload_file URL or local path"
    },
    "headlines": {
      "description": "your own headlines to test (up to 10); omit to have them written",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "count": {
      "description": "how many headlines to write when `headlines` is omitted (default 5)",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "brief": {
      "description": "what to test, e.g. \"price-led vs outcome-led\" or \"speak to busy parents\"",
      "type": "string"
    }
  },
  "required": [
    "image"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "the finished static ad: URL, Library item URL, upload_file URL or local path"
    },
    "aspectRatios": {
      "description": "target canvases (default 1:1, 4:5, 9:16)",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "1:1",
          "4:5",
          "9:16",
          "16:9",
          "3:4",
          "4:3"
        ]
      }
    }
  },
  "required": [
    "image"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "the finished static ad: URL, Library item URL, upload_file URL or local path"
    },
    "languages": {
      "minItems": 1,
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "target languages, by name"
    }
  },
  "required": [
    "image",
    "languages"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "framework": {
      "description": "concept framework id (default 'posed_portrait'), or your own concept in words",
      "type": "string"
    },
    "frameworkRequested": {
      "description": "true ONLY when the USER named this framework — it is what authorizes a text-carrying framework (social_ui / news_clip / specific_day / map_aerial) to bake its short UI label",
      "type": "boolean"
    },
    "sceneBrief": {
      "description": "what the thumbnail depicts — the concept in one dense sentence, rendered exactly",
      "type": "string"
    },
    "topic": {
      "description": "the video's topic — used to pick the hero object when you don't name keyElements",
      "type": "string"
    },
    "headline": {
      "description": "2–4 word headline. Typeset OVER the finished render by default (free, always legible); newlines split it into stacked lines",
      "type": "string"
    },
    "headlineLines": {
      "description": "explicit headline lines (up to 3) — overrides splitting `headline` on newlines",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "bakeText": {
      "description": "default false. true paints the headline INTO the generation — only on an explicit user ask; it leaks garbled text elsewhere in the frame",
      "type": "boolean"
    },
    "bakedUiText": {
      "description": "short label for a text-carrying framework (a chat bubble, a DAY N badge, a news lower-third, a map callout) — needs frameworkRequested:true",
      "type": "string"
    },
    "overlayStyle": {
      "description": "headline style: beast (default), fire, neon-lime, clean-glass, marker, or your own CSS declarations",
      "type": "string"
    },
    "font": {
      "description": "headline font: Anton (default) or any Google Fonts family",
      "type": "string"
    },
    "headlinePlace": {
      "description": "bottom (default), top, center, or a 0-1 fraction from the top; never over the face",
      "type": "string"
    },
    "faceImages": {
      "description": "up to 3 face photos (URLs or local paths) — each becomes a locked CHARACTER identity, in order",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "people": {
      "description": "people described in prose instead of by photo (each still gets the chosen expression)",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "describe": {
            "type": "string"
          }
        },
        "required": [
          "describe"
        ],
        "additionalProperties": {}
      }
    },
    "castGenericPerson": {
      "description": "pass true only after the user has explicitly chosen a generated stranger over their own face",
      "type": "boolean"
    },
    "emotion": {
      "description": "the expression on the face (default 'shock') — a preset id or your own phrase",
      "type": "string"
    },
    "emotions": {
      "description": "render one variant per emotion (variants = emotions × takes, max 16)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "takes": {
      "description": "camera takes per emotion, 1–4: designed framing / low-angle hero / extreme close-up / wide dutch tilt",
      "type": "number"
    },
    "variants": {
      "description": "how many thumbnails to render (default 1, max 16). Each is its own billed render — offer a set of 4 rather than assuming",
      "type": "number"
    },
    "aspectRatio": {
      "description": "'16:9' (YouTube, default) / '9:16' (Shorts) / '4:5' (Instagram) / '4:3' / '1:1'",
      "type": "string"
    },
    "keyElements": {
      "description": "signature props / effects that make it pop — oversized, flying toward camera",
      "type": "string"
    },
    "location": {
      "description": "place, time of day, weather, atmosphere",
      "type": "string"
    },
    "composition": {
      "description": "override the default large-foreground-subject composition",
      "type": "string"
    },
    "background": {
      "description": "override the default bold saturated colour-field background",
      "type": "string"
    },
    "rimColor": {
      "description": "colored back+hair light — ONLY when the user names one: 'ice-blue' / 'neon-magenta' / 'toxic-lime' / 'amber-gold' / 'pure-white'",
      "type": "string"
    },
    "restrainedGrade": {
      "description": "true for a calm / premium / muted look instead of the default punchy poster grade",
      "type": "boolean"
    },
    "logo": {
      "description": "a brand logo URL or path to place into the composition",
      "type": "string"
    },
    "logo3d": {
      "description": "first turn the flat logo into a volumetric 3D render (one extra billed image), then composite that",
      "type": "boolean"
    },
    "split": {
      "description": "split/panel LAYOUT — only when the user asks for one (\"split\", \"before/after\", \"versus screen\"). \"X vs Y\" as a SCENE stays one unified frame",
      "type": "object",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "plain",
            "before_after",
            "versus",
            "custom"
          ]
        },
        "panels": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "mode"
      ],
      "additionalProperties": {}
    },
    "reference": {
      "description": "fields YOU extracted by eye from a reference thumbnail. Extract ALL of: brief (one dense sentence on the concept), subject (pose/action generically, NEVER a specific identity), elements, location, composition, background, split (boolean), split_count, person_count (0-3), emotion (one of the 11 presets or 'other'), emotion_detail (one vivid sentence covering eyes, brows, mouth, head angle). emotion + emotion_detail carry the reference's actual facial performance, which is the single biggest CTR lever on a face; split/split_count reproduce its panel structure. The reference image itself is never sent to the model",
      "type": "object",
      "properties": {},
      "additionalProperties": {}
    },
    "tweak": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      },
      "required": [
        "kind",
        "value"
      ],
      "description": "surgical pixel-faithful edit of a FINISHED thumbnail (needs sourceImage): kind emotion / background / background_color / rim_light, or any other kind with the edit in words as value"
    },
    "sourceImage": {
      "description": "the finished thumbnail URL a `tweak` edits; tweaks chain, so feed each accepted output into the next",
      "type": "string"
    },
    "forceGenerate": {
      "description": "render the 'screenshot' framework anyway (it is normally a real video frame, not a generation)",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "the script to speak (≤900 characters)"
    },
    "engine": {
      "description": "voice-engine id: 'seed-audio' (default), 'eleven-v3', 'minimax-speech', or 'kokoro' — listed in hermoso_capabilities",
      "type": "string"
    },
    "voice": {
      "description": "a voice preset from the chosen engine (e.g. 'Aria'/'George' on eleven-v3, 'stokie_en' on seed-audio) — omit for the engine default",
      "type": "string"
    }
  },
  "required": [
    "text"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "the music in words, e.g. 'lo-fi jazz, brushed drums, 80 bpm'"
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "the writing task / question"
    },
    "raw": {
      "description": "RAW MODEL ACCESS: send the prompt with NO Hermoso system prompt — the model answers as itself rather than as an ad copywriter. Use it whenever the ask is not marketing copy (analysis, code, extraction, a plain question). Default false: the copywriter framing is applied.",
      "type": "boolean"
    },
    "model": {
      "description": "a writing-model id from hermoso_capabilities (a Claude / Gemini / GPT / Llama / DeepSeek id) — omit for the default",
      "type": "string"
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "creative": {
      "type": "object",
      "properties": {},
      "additionalProperties": {},
      "description": "the FULL structured output of plan_ad (must contain video_storyboard)"
    },
    "creator": {
      "description": "CAST A SAVED CREATOR in this ad — their id from list_creators, or the name you know them by (“Sarah”). Their saved portrait becomes the on-camera identity for the whole spot, so the same face carries across every act and across every ad you render for this brand — and because we already have their picture, the character portrait this pipeline would otherwise generate is skipped, so casting somebody costs LESS than not casting them. Omit to let the ad cast a fresh person — EXCEPT for a CREATOR account (onboarded from their own @handle): their own saved likeness is cast by default on any plan with a person on camera, and the read-back says `default:true`; pass \"none\" to render without them. Refused for free, with nothing rendered, if the name matches nobody or more than one creator, or if an explicitly named creator is cast on a plan with nobody on camera. Casting a REAL person confirms their likeness consent.",
      "type": "string"
    },
    "model": {
      "description": "video model id from hermoso_capabilities (default: the plan’s pick). Naming one is a DELIBERATE pick — the server asks before ever swapping it (no silent fallback)",
      "type": "string"
    },
    "durationSeconds": {
      "description": "total ad length in seconds (supported range 4–180; outside that it is clamped). Omit to honor the plan’s own duration — that is almost always right. This only RE-TIMES an already-authored board (its scenes are scaled to fit), it does NOT re-write it, so to change the length of the ad the user asked for, re-run plan_ad with durationSeconds instead. A length that fits ONE clip of the render model renders as one continuous pass; longer is stitched from acts filled to that model’s clip maximum with the remainder last — the maximum is 15s on most models and 30s on the longest-clip one, so use dryRun:true to see the exact act split for free before spending.",
      "type": "number"
    },
    "aspectRatio": {
      "description": "output aspect ratio, e.g. 9:16 (default) / 1:1 / 16:9",
      "type": "string"
    },
    "resolution": {
      "description": "'1080p' default (what we ship and bill for); '480p'/'720p' = cheaper draft passes, '4k' = premium final delivery (more credits). NOT EVERY MODEL OFFERS EVERY TIER — this enum is what the tool accepts, and each model's OWN `resolutions` list in hermoso_capabilities is what it can actually render (the longest-clip 30s model, for one, tops out at 720p). Ask for a tier the chosen model does not list and it is rendered at that model's best available tier instead, with nothing in the reply saying so — so check `resolutions` before promising anyone 1080p or 4k.",
      "type": "string",
      "enum": [
        "480p",
        "720p",
        "1080p",
        "4k"
      ]
    },
    "captions": {
      "description": "burn the plan's per-scene on-screen words as caption pills. DEFAULT FALSE on every recipe — set true ONLY when the user asks for on-screen text or captions; no recipe turns them on by itself",
      "type": "boolean"
    },
    "endCard": {
      "description": "append the branded end card. DEFAULT FALSE on every recipe — set true ONLY when the user asks for an end card (a clone of a video that had none should not grow one)",
      "type": "boolean"
    },
    "music": {
      "description": "music bed: on (default), false, or the bed described in words ('lo-fi jazz, brushed drums')",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string"
        }
      ]
    },
    "lockup": {
      "description": "brand wordmark + tagline composited over the closing seconds. DEFAULT FALSE — set true ONLY when the user asks for branding on the close",
      "type": "boolean"
    },
    "textStyle": {
      "description": "THE LOOK of captions and the end card, only with captions or endCard and only when the user described one: the look in WORDS (\"chunky yellow comic letters, purple outline\"), a preset (editorial: big serif title + small italic line; bold: condensed caps, outline; minimal; handwritten; boxed; pill, the default), or fields. \"TITLE · small line\" puts the part after the dot on a second line.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {
            "preset": {
              "type": "string"
            },
            "describe": {
              "description": "the look in words",
              "type": "string"
            },
            "font": {
              "description": "sans|serif|elegant|condensed|hand or any Google Fonts family",
              "type": "string"
            },
            "subFont": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "size": {
              "description": "s|m|l|xl, '120px', or a 0.015-0.15 frame fraction",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                }
              ]
            },
            "color": {
              "description": "any CSS colour",
              "type": "string"
            },
            "outlineColor": {
              "type": "string"
            },
            "background": {
              "description": "none|pill|a colour",
              "type": "string"
            },
            "position": {
              "description": "top|center|lower|bottom or 0.05-0.95 from the top",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                }
              ]
            },
            "textCase": {
              "type": "string",
              "enum": [
                "as-is",
                "upper",
                "lower",
                "title"
              ]
            },
            "italic": {
              "type": "boolean"
            },
            "subItalic": {
              "type": "boolean"
            },
            "outline": {
              "type": "boolean"
            },
            "shadow": {
              "type": "boolean"
            },
            "tilt": {
              "description": "degrees, ±45",
              "type": "number"
            },
            "cardColor": {
              "type": "string"
            }
          }
        }
      ]
    },
    "ttsVoice": {
      "description": "voiceover voice name (e.g. Rachel / George) when the plan voices over",
      "type": "string"
    },
    "dryRun": {
      "description": "return the routing decision (single pass vs stitched acts, resolved model + act lengths) WITHOUT submitting a render — free, nothing charged",
      "type": "boolean"
    },
    "allowGenericProduct": {
      "description": "proceed even though this brand has NO product photo on file and the ad features a product — the packaging will be INVENTED. Only pass true after telling the user that and hearing they are fine with a generic stand-in",
      "type": "boolean"
    }
  },
  "required": [
    "creative"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "config": {
      "type": "object",
      "properties": {},
      "additionalProperties": {},
      "description": "MUST include config.template: 'custom' or a preset id above, plus its fields"
    }
  },
  "required": [
    "config"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "videoUrl": {
      "type": "string",
      "description": "the served URL of the video to finish (from a previous render/job)"
    },
    "header": {
      "description": "header pill copy, ≤40 chars (required when pills is on)",
      "type": "string"
    },
    "sub": {
      "description": "accent sub-pill copy, ≤34 chars (usually the product/brand)",
      "type": "string"
    },
    "points": {
      "description": "3-4 proof points, ≤44 chars each",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "accent": {
      "description": "brand accent hex for the sub-pill",
      "type": "string"
    },
    "pills": {
      "description": "default true — set false for a grain-only pass",
      "type": "boolean"
    },
    "grain": {
      "description": "default false — anti-AI film-grain finish",
      "type": "boolean"
    }
  },
  "required": [
    "videoUrl"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "videoUrl": {
      "type": "string",
      "description": "the video to edit: a render / Library URL, a direct file, or a public post link"
    },
    "ops": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "op": {
            "type": "string",
            "enum": [
              "trim",
              "speed",
              "mute",
              "audio_gain",
              "fade_out",
              "append_card",
              "watermark",
              "grain",
              "text",
              "join"
            ]
          },
          "start": {
            "description": "trim/mute/text window start (s)",
            "type": "number"
          },
          "end": {
            "description": "trim/mute/text window end (s)",
            "type": "number"
          },
          "text": {
            "description": "text: the words, verbatim",
            "type": "string"
          },
          "position": {
            "description": "text: where",
            "type": "string",
            "enum": [
              "top",
              "center",
              "lower",
              "bottom"
            ]
          },
          "style": {
            "description": "text: a look name or a textStyle",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {},
                "additionalProperties": {}
              }
            ]
          },
          "textStyle": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {},
                "additionalProperties": {}
              }
            ]
          },
          "clips": {
            "description": "join: the clips after this video",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "start": {
                  "type": "number"
                },
                "end": {
                  "type": "number"
                },
                "match": {}
              },
              "required": [
                "url"
              ]
            }
          },
          "match": {
            "description": "join: seam match, 'auto' default | 'off' | {grade,level,grain,blur,strength}"
          },
          "transition": {
            "description": "join",
            "type": "string",
            "enum": [
              "cut",
              "crossfade"
            ]
          },
          "bridge": {
            "description": "join: connects the hook to the first clip",
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "impact",
                  "text"
                ]
              },
              "cutAt": {
                "description": "omit: found from the footage",
                "type": "number"
              },
              "matchCut": {
                "type": "number"
              },
              "sound": {
                "type": "string",
                "enum": [
                  "auto",
                  "own",
                  "impact",
                  "whoosh",
                  "none"
                ]
              },
              "flash": {
                "type": "boolean"
              },
              "shake": {
                "type": "boolean"
              },
              "text": {
                "type": "string"
              },
              "then": {
                "type": "string"
              }
            },
            "required": [
              "kind"
            ]
          },
          "factor": {
            "description": "speed 0.5-2",
            "type": "number"
          },
          "db": {
            "description": "audio_gain -20..+6 dB",
            "type": "number"
          },
          "seconds": {
            "description": "fade_out 0.3-3s / append_card 2-5s / crossfade 0.2-1.5s",
            "type": "number"
          },
          "headline": {
            "description": "append_card: big line (defaults to the brand name)",
            "type": "string"
          },
          "tagline": {
            "description": "append_card: smaller line under the headline",
            "type": "string"
          },
          "sub": {
            "description": "append_card: the pill line (defaults to the website) / text: a smaller second line",
            "type": "string"
          },
          "background": {
            "description": "append_card: card background — hex or a color name ('red', 'navy'…); the user's stated color always wins over the brand palette",
            "type": "string"
          },
          "card_html": {
            "description": "append_card: your OWN full-frame card design as inline-styled HTML ({{logo}} inserts the real brand logo) — use when the standard layout cannot honor the request",
            "type": "string"
          },
          "corner": {
            "description": "watermark corner (default br)",
            "type": "string",
            "enum": [
              "tl",
              "tr",
              "bl",
              "br"
            ]
          },
          "intensity": {
            "description": "grain look",
            "type": "string",
            "enum": [
              "default",
              "strong"
            ]
          }
        },
        "required": [
          "op"
        ]
      },
      "description": "the ordered edit plan (max 6 ops)"
    },
    "brandName": {
      "description": "override the workspace brand name",
      "type": "string"
    },
    "domain": {
      "description": "override the brand website",
      "type": "string"
    },
    "accent": {
      "description": "override the brand accent hex",
      "type": "string"
    }
  },
  "required": [
    "videoUrl",
    "ops"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "videoUrl": {
      "type": "string",
      "description": "the served URL of the master video to fix"
    },
    "startSeconds": {
      "type": "number",
      "description": "window start in seconds"
    },
    "endSeconds": {
      "type": "number",
      "description": "window end in seconds (window 1.5-8s)"
    },
    "prompt": {
      "type": "string",
      "description": "what the replacement footage should show — describe the shot, matching the master's style"
    },
    "refImage": {
      "description": "optional product/style anchor image URL",
      "type": "string"
    },
    "speechWindows": {
      "description": "[[start,end],...] windows with spoken lines — the fix window must not overlap these",
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "number"
        }
      }
    }
  },
  "required": [
    "videoUrl",
    "startSeconds",
    "endSeconds",
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "video": {
      "type": "string",
      "description": "the long video to clip — a YouTube/Vimeo/Loom/Dailymotion/Streamable/Rumble/Wistia/Twitch/TED watch URL, a direct https .mp4/.mov/.webm, or a Hermoso /generated/ URL"
    },
    "count": {
      "description": "how many clips to cut, 1-8 (default 4)",
      "type": "number"
    },
    "aspectRatio": {
      "description": "clip shape: '9:16' (default), '1:1', '16:9', any 'W:H', or 'keep' for the source framing",
      "type": "string"
    },
    "captions": {
      "description": "burn subtitles into every clip. DEFAULT TRUE — a clip cut from a podcast or a talk is watched on mute, and the words are the product. Set false for clean footage. A clip whose window carries no readable speech is delivered bare rather than captioned with a guess, and the result says which.",
      "type": "boolean"
    }
  },
  "required": [
    "video"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "video": {
      "type": "string",
      "description": "the video to subtitle"
    },
    "textStyle": {
      "description": "the look: words, a preset or fields; omit for the default",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {
            "preset": {
              "type": "string"
            },
            "describe": {
              "description": "the look in words",
              "type": "string"
            },
            "font": {
              "description": "sans|serif|elegant|condensed|hand or any Google Fonts family",
              "type": "string"
            },
            "subFont": {
              "type": "string"
            },
            "weight": {
              "type": "number"
            },
            "size": {
              "description": "s|m|l|xl, '120px', or a 0.015-0.15 frame fraction",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                }
              ]
            },
            "color": {
              "description": "any CSS colour",
              "type": "string"
            },
            "outlineColor": {
              "type": "string"
            },
            "background": {
              "description": "none|pill|a colour",
              "type": "string"
            },
            "position": {
              "description": "top|center|lower|bottom or 0.05-0.95 from the top",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                }
              ]
            },
            "textCase": {
              "type": "string",
              "enum": [
                "as-is",
                "upper",
                "lower",
                "title"
              ]
            },
            "italic": {
              "type": "boolean"
            },
            "subItalic": {
              "type": "boolean"
            },
            "outline": {
              "type": "boolean"
            },
            "shadow": {
              "type": "boolean"
            },
            "tilt": {
              "description": "degrees, ±45",
              "type": "number"
            },
            "cardColor": {
              "type": "string"
            }
          }
        }
      ]
    },
    "burn": {
      "description": "false = only the .srt",
      "type": "boolean"
    },
    "auto": {
      "type": "string",
      "enum": [
        "sentences",
        "words"
      ]
    },
    "wordsPerCue": {
      "type": "number"
    },
    "cues": {
      "description": "your own lines in seconds, no overlap, max 90 chars, no emoji",
      "maxItems": 400,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "start": {
            "type": "number"
          },
          "end": {
            "type": "number"
          }
        },
        "required": [
          "text",
          "start",
          "end"
        ]
      }
    }
  },
  "required": [
    "video"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "what the explainer should teach or explain — a topic or a short brief"
    },
    "durationSeconds": {
      "description": "target length 20-120s (default 60); drives the section count — ~10s of narration each, 3-8 sections",
      "type": "number"
    },
    "frameDensity": {
      "description": "how many pictures per second of narration, and therefore what it costs. 'standard' (default) is a frame about every 1.5s — the density a stills film needs to read as a film rather than a slideshow; 'lean' is one about every 2.5s (the longest hold that still reads as a film, ~40% of the frames and ~40% of the cost); 'minimal' is ONE picture per narration section, which is cheapest and is frankly a slideshow. Only drop below the default if the user asked for something cheaper.",
      "type": "string",
      "enum": [
        "standard",
        "lean",
        "minimal"
      ]
    },
    "aspectRatio": {
      "description": "'9:16' default",
      "type": "string",
      "enum": [
        "9:16",
        "16:9",
        "1:1",
        "4:5",
        "3:4"
      ]
    },
    "style": {
      "description": "visual style: 'cinematic' (default, photoreal); styled shortcuts editorial_collage, flat_vector, stickman, whiteboard, ink_marker, silhouette, storybook, paper_diorama, isometric, claymation, pixel_art, watercolor, fluffy_toy, low_poly, stylized_3d, studio_3d (the Kids default), mannequin; or ANY look described in words ('80s anime cel animation'), locked across every frame. Ask rather than pick silently; a styled look costs more.",
      "type": "string"
    },
    "channel": {
      "description": "the CHANNEL TYPE — it sets the pacing, the narration register and the default look, and is orthogonal to `style` (a named style always wins): explainer (casual second-person, fast cuts), history (witty chronological retelling / documentary), kids (fastest, question-first, warm teacher), fairytale (slow, atmospheric myth or folklore). Default 'explainer'.",
      "type": "string",
      "enum": [
        "explainer",
        "history",
        "kids",
        "fairytale"
      ]
    },
    "voice": {
      "description": "narration voice name — omit for the default warm read",
      "type": "string"
    },
    "captions": {
      "description": "turn ON-SCREEN TEXT on. DEFAULT FALSE, and leave it false unless the user asks — the narration already says the point and the pictures carry it, so the clean film is the better default. `captions:true` on its own burns SUBTITLES (see below), because that is what a caption is for: showing what is being said when the phone is on mute. Slim white CAPS, thin black outline, bottom safe band, no plate, no box.",
      "type": "boolean"
    },
    "subtitles": {
      "description": "which on-screen text, once `captions` is on. LEAVE IT UNSET (or true) for SUBTITLES — every spoken word, in order, timed to the narration; free, no extra render, no extra credits, and there is NO cue limit, so the whole film is subtitled however long it runs (at most 5 words / 32 characters a line). Set it FALSE only if the user explicitly wants section HEADINGS instead: one short summary label held over each ~7-15s section. That is NOT what is being said — it is a label about it — so it is the wrong answer to \"add captions\" and to anyone watching on mute. `subtitles:true` also implies `captions:true`. TIMING: each cue is anchored to that section’s REAL measured narration length and distributed inside the section by character count — exact at every section boundary, approximate to a few tenths of a second within one. It is not a word-level speech clock, so never promise frame-accurate sync.",
      "type": "boolean"
    },
    "music": {
      "description": "music bed under the narration, measured to sit about 14 dB under the voice and sidechain-ducked beneath it. Omit and the KIDS and FAIRYTALE channels get their recommended bed COMPOSED for this film — those two are the only channels a bed is due on unasked, and it costs a small flat fee; every other channel ships dry. 'off' forces silence. 'library' takes a free curated track only, and ships dry when none is on file. NAME A MOOD (upbeat / calm / warm / epic / tense / playful / elegant / hype / chill / dramatic) or DESCRIBE it in words to compose one on ANY channel, at the same fee. hermoso_capabilities reports the exact figure as explainerMusicCredits; quote it before you turn a bed on or pick a mood.",
      "type": "string"
    },
    "upscale": {
      "description": "optional FINAL upscale — 2 doubles each side, 4 quadruples. Captions and the end card are burned BEFORE it so they upscale with the frame. It is priced BY LENGTH and it is the expensive part — several times the cost of rendering the film itself. hermoso_capabilities reports the exact figures per length as explainerUpscaleCredits. Never turn it on unasked: quote the number and let the user choose.",
      "type": "number"
    },
    "endCard": {
      "description": "append the branded end card. DEFAULT FALSE — set true ONLY when the user asks for one",
      "type": "boolean"
    },
    "brandName": {
      "description": "brand name for the end card — omit to leave it unbranded",
      "type": "string"
    }
  },
  "required": [
    "topic"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "what the sizzle should show — the product, the setting, the look"
    },
    "seconds": {
      "description": "finished length, clamped to 18-30s (default 25). The PAID hero render is always 15s regardless — this only changes how the cuts and cards are packed",
      "type": "number"
    },
    "refImage": {
      "description": "product packshot URL that anchors the real label — strongly recommended",
      "type": "string"
    },
    "aspectRatio": {
      "description": "'9:16' default; anything the seedance-2 catalog entry does not list falls back to 9:16",
      "type": "string"
    },
    "resolution": {
      "description": "hero-clip resolution and therefore the whole cost — DEFAULT '1080p' (≈1,040 credits); '720p' ≈470, '480p' ≈220, '4k' ≈4,130",
      "type": "string",
      "enum": [
        "480p",
        "720p",
        "1080p",
        "4k"
      ]
    },
    "specs": {
      "description": "up to 4 spec lines for the typeset cards, ≤26 chars each",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "cta": {
      "description": "closing CTA line, ≤30 chars",
      "type": "string"
    },
    "brandName": {
      "description": "brand name on the cards — defaults to the workspace brand",
      "type": "string"
    },
    "musicMood": {
      "description": "music-bed mood, e.g. driving / cinematic / upbeat",
      "type": "string"
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "the video prompt / shot description (for a refVideo edit, this is the transformation instruction)"
    },
    "raw": {
      "description": "RAW MODEL ACCESS: dispatch this prompt to the model BYTE-IDENTICAL — no appended packaging/label guidance, no negative prompt, no reference-binding lines, no hex-to-colour-name rewrite. Use it when you want the model itself rather than Hermoso's render craft. Two vendor-required fixes still apply: extra @ImageN tokens are dropped and an over-long prompt is trimmed at a sentence. Billing, durable delivery and per-model validation are unchanged.",
      "type": "boolean"
    },
    "refImage": {
      "description": "local path or URL to anchor the first frame; a real person’s photo here or in refImages confirms their likeness consent",
      "type": "string"
    },
    "refImages": {
      "description": "SEVERAL reference images (local paths or URLs) — a person, products, a place — that must all appear in the clip. Only models whose `refs.max` in hermoso_capabilities is above 1 use more than one, and each uses at most that many; with `refs.promptAddressed` true, name them in your prompt as Image 1, Image 2… in this order. minimax-h3-max-ref takes up to 9 and keeps each one as a reference rather than a first frame. On a model that takes one image, only the first is used.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "refVideo": {
      "description": "URL of an existing video to EDIT rather than generate from scratch — the clip is transformed per your prompt, inheriting the SOURCE clip’s canvas (aspect ratio) and, on every model hermoso_capabilities marks `sourceLength`, its LENGTH too: those endpoints have no duration parameter, their listed `durations` are the per-second price ladder, and a durationSeconds you send is reported back as unused rather than silently dropped. Trim the source to change the length. Omit `model` for the default editor, or name a model whose videoEdit is true in hermoso_capabilities (a named model that cannot edit is refused, nothing charged); refImage rides along as the look of what the edit adds. With extend:true this is instead the clip to EXTEND. Omit to generate a fresh clip.",
      "type": "string"
    },
    "endImage": {
      "description": "local path or URL of the LAST frame: the clip travels from refImage (required with it) to this image. Only models with endFrame true in hermoso_capabilities take it; any other named model is refused by name, nothing charged.",
      "type": "string"
    },
    "loop": {
      "description": "true = a seamless loop whose last frame flows back into its first. Only models with loop true in hermoso_capabilities; needs refImage and cannot be combined with endImage.",
      "type": "boolean"
    },
    "shots": {
      "description": "MULTI-SHOT: one clip cut into these shots, in order. The seconds must add up to a length the model renders; replaces `prompt` (send either). Only models with multiShot true in hermoso_capabilities.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "what happens in this shot"
          },
          "seconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 15,
            "description": "this shot’s length in whole seconds"
          }
        },
        "required": [
          "prompt",
          "seconds"
        ]
      }
    },
    "extend": {
      "description": "true = EXTEND refVideo: the same clip continues per your prompt for durationSeconds more (each model’s extend.minSeconds..maxSeconds in hermoso_capabilities), delivered as ONE clip, source then continuation. Needs model named (a model with extend in hermoso_capabilities).",
      "type": "boolean"
    },
    "interactionId": {
      "description": "with extend:true on an Omni model: the interactionId returned by an earlier render on that model — continues it from its own stored context instead of re-uploading refVideo.",
      "type": "string"
    },
    "durationSeconds": {
      "description": "length of THIS ONE clip in seconds — pick one of the CHOSEN model’s listed durations from hermoso_capabilities (never a generic guess: the lists differ per model, from 4–8s on the short models up to 30s on the longest-clip one). This is a single continuous generation, so it CANNOT exceed that model’s longest clip: a longer ask is REFUSED with nothing rendered and nothing charged (it is never quietly truncated). Past ~15s only the long-clip models qualify, and an unnamed render is routed by the narrower auto-pool — so NAME the model in `model` when you are asking for a long single take. For a spot longer than any one clip, use plan_ad with durationSeconds then render_ad, which stitches acts of at most one model clip each (on a 15s-clip model, 40s = 15+15+10).",
      "type": "number"
    },
    "aspectRatio": {
      "description": "default '9:16'",
      "type": "string"
    },
    "model": {
      "description": "video model id from hermoso_capabilities; a named model is never swapped without asking. Omit to let the router pick",
      "type": "string"
    },
    "resolution": {
      "description": "'1080p' default (what we ship and bill for); '480p'/'720p' = cheaper draft passes, '4k' = premium final delivery (more credits). NOT EVERY MODEL OFFERS EVERY TIER — this enum is what the tool accepts, and each model's OWN `resolutions` list in hermoso_capabilities is what it can actually render. Ask for a tier the chosen model does not list and it is rendered at that model's best available tier instead, with nothing in the reply saying so — so check `resolutions` before promising anyone 1080p or 4k.",
      "type": "string",
      "enum": [
        "480p",
        "720p",
        "1080p",
        "4k"
      ]
    },
    "cameraMove": {
      "description": "A named camera move around the still in refImage, spelled exactly as the enum gives it: an orbit (a quarter turn, the default), orbiting left, a half turn or a full turntable, a rise, a crane up, a push in, a pull back, or a reveal. Only the camera-controls model renders one (minimax-h3-max-camera, listed with its moves in hermoso_capabilities): pass it with model omitted and that model is picked, or with that model named; any other named model is refused by name with nothing charged. Needs refImage.",
      "type": "string",
      "enum": [
        "orbit",
        "orbit_left",
        "orbit_half",
        "orbit_full",
        "rise",
        "crane_up",
        "push_in",
        "pull_back",
        "reveal"
      ]
    },
    "cameraTrajectory": {
      "description": "Your own ordered camera path, 2 to 12 keyframes, for the camera-controls model only (same rule as cameraMove; overrides it). The first pose is held until its time and the last pose is held to the end. A value outside these bounds is refused by name, nothing charged.",
      "minItems": 2,
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "time": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "when this pose is reached, 0 = start of the clip, 1 = end"
          },
          "azimuth": {
            "type": "number",
            "description": "horizontal angle around the subject in degrees (0 = where the still was taken; the sign turns the camera the other way; at most 32 full turns of total travel)"
          },
          "elevation": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "vertical angle in degrees, -90 (below) to 90 (straight above)"
          },
          "distance": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "distance from the subject in scene units, 1 = the distance of the still; smaller is closer"
          }
        },
        "required": [
          "time",
          "azimuth",
          "elevation",
          "distance"
        ]
      }
    },
    "ttsScript": {
      "description": "voiceover script to speak",
      "type": "string"
    },
    "ttsVoice": {
      "description": "voice name, e.g. Rachel / George",
      "type": "string"
    },
    "musicMood": {
      "description": "WHICH mood the music bed is composed in (upbeat / calm / warm / epic / tense / playful / elegant / hype / chill / dramatic). It does NOT decide WHETHER there is one: a clip that comes back with no audio track — every model hermoso_capabilities lists as \"silent\", plus any audio model that returned mute — gets a bed composed and CHARGED automatically, at the flat per-track fee hermoso_capabilities reports as explainerMusicCredits, and omitting this field only means the mood defaults to \"warm\". Pass audio:false for a genuinely silent clip with no bed and no bed charge.",
      "type": "string"
    },
    "audio": {
      "description": "default true. false = render SILENT: no native model audio, no music bed, and no bed charge held or billed. This is the ONLY way to decline the automatic bed (see musicMood) — leave it alone for anything that should have sound, and do not combine it with ttsScript.",
      "type": "boolean"
    }
  },
  "required": [
    "prompt"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "local path or URL of the presenter portrait; a real person’s photo confirms their likeness consent"
    },
    "script": {
      "type": "string",
      "description": "the words the avatar speaks"
    },
    "voice": {
      "description": "voice name (Rachel/Sarah/George/Adam)",
      "type": "string"
    },
    "resolution": {
      "description": "'1080p' (default) or '480p'/'720p' draft",
      "type": "string"
    }
  },
  "required": [
    "image",
    "script"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "scenes": {
      "minItems": 2,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {},
        "additionalProperties": {}
      },
      "description": "array of scene objects (visual + optional voiceover/seconds)"
    },
    "aspectRatio": {
      "description": "output aspect ratio, e.g. 9:16 (default) / 1:1 / 16:9",
      "type": "string"
    },
    "voiceover": {
      "description": "full voiceover script spoken across the scenes",
      "type": "string"
    },
    "voice": {
      "description": "voiceover voice name, e.g. Rachel / George",
      "type": "string"
    },
    "resolution": {
      "description": "720p (default), 1080p for full detail, or 480p for a cheaper draft",
      "type": "string"
    },
    "model": {
      "description": "video model id from hermoso_capabilities — omit to let the router pick",
      "type": "string"
    },
    "durationSeconds": {
      "description": "total spot length in seconds (defaults to the sum of the scenes’ seconds)",
      "type": "number"
    }
  },
  "required": [
    "scenes"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the job id, e.g. job_xxx"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "bundle name from list_skills, e.g. hermoso-generate"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "short skill name, e.g. “Founder-story hook”"
    },
    "directive": {
      "type": "string",
      "description": "the full instruction the skill applies when used (1–6 sentences, imperative)"
    }
  },
  "required": [
    "name",
    "directive"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the custom skill id (from list_skills)"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "category": {
      "description": "filter to one bucket (Brand/Audience/Taste/Do/Don’t/Preference)",
      "type": "string"
    },
    "limit": {
      "description": "max items (default 50, max 200)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "the fact/preference, concise"
    },
    "category": {
      "description": "short bucket: Brand, Audience, Taste, Do, Don’t, or Preference (default General)",
      "type": "string"
    }
  },
  "required": [
    "text"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the memory item id (from list_memory)"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "confirm": {
      "description": "true to APPLY the proposal; omit to only see it",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "collection": {
      "description": "only list ads in this collection (by name or id) — omit for every collection",
      "type": "string"
    },
    "limit": {
      "description": "max ads to return (default 50, max 500)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "collection": {
      "type": "string",
      "description": "the collection name — an existing one, or a new one to create"
    },
    "items": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "description": "a stable id for this ad if you have one (an ad_archive_id, creativeId, …). Omit and one is derived from the link/media so re-saving is idempotent",
            "type": "string"
          },
          "advertiser": {
            "description": "the brand running the ad",
            "type": "string"
          },
          "page_name": {
            "description": "alias of advertiser: the field search_meta_ads returns, accepted as-is",
            "type": "string"
          },
          "pageName": {
            "description": "alias of advertiser",
            "type": "string"
          },
          "title": {
            "description": "headline / hook",
            "type": "string"
          },
          "body": {
            "description": "the ad copy",
            "type": "string"
          },
          "image": {
            "description": "image URL",
            "type": "string"
          },
          "video": {
            "description": "video URL",
            "type": "string"
          },
          "link": {
            "description": "link to the ad in its library / the destination URL",
            "type": "string"
          },
          "platform": {
            "description": "where it ran — 'meta', 'google', 'linkedin', 'tiktok', 'generated', …",
            "type": "string"
          }
        },
        "additionalProperties": {}
      },
      "description": "the ads to save"
    }
  },
  "required": [
    "collection",
    "items"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "the saved row's key from list_swipefile, e.g. tiktok:handle"
    },
    "status": {
      "type": "string",
      "enum": [
        "new",
        "contacted",
        "replied",
        "booked",
        "passed"
      ]
    },
    "note": {
      "description": "replaces the existing note; pass \"\" to clear it",
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "max playbooks to return (default 25, max 100)",
      "type": "number"
    },
    "full": {
      "description": "true to return every hook/angle/play in the text, not just the headline counts",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "the playbook headline — what it is, in a few words"
    },
    "hooks": {
      "description": "the opening hooks worth reusing, verbatim",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "angles": {
      "description": "the persuasion angles ({title, detail})",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          }
        },
        "required": [
          "title"
        ],
        "additionalProperties": {}
      }
    },
    "formats": {
      "description": "the formats/recipes this plays best in (e.g. ugc_selfie, cinematic, static)",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "plays": {
      "description": "the concrete plays to run ({title, detail}) — the actionable half",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          }
        },
        "required": [
          "title"
        ],
        "additionalProperties": {}
      }
    },
    "brand": {
      "description": "which brand this is for (defaults to the workspace brand)",
      "type": "string"
    },
    "source": {
      "description": "where it came from, e.g. “teardown · Ridge”",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the playbook id (from list_playbooks)"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "max creators to return (default 24)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "what to call this creator (e.g. “Sarah”) — list_creators and the app’s picker match on it"
    },
    "image": {
      "description": "REQUIRED except with useAnyway. public https url of the portrait (an existing render’s url, or any public photo). Not a local file path — upload it with upload_file first and save the url that returns",
      "type": "string"
    },
    "source": {
      "description": "\"generated\" (default) = an AI-made person; \"upload\" / \"social\" = a REAL person",
      "type": "string",
      "enum": [
        "generated",
        "upload",
        "social"
      ]
    },
    "voice": {
      "description": "a default voice name for this persona (engines + voices are in hermoso_capabilities)",
      "type": "string"
    },
    "poses": {
      "description": "up to 4 extra full-body / angle plates of the SAME person (public urls) — they make a wider shot hold the identity",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "look": {
      "description": "their canonical wardrobe/appearance in words — reused to hold the look steady across ads",
      "type": "string"
    },
    "useAnyway": {
      "description": "only for a creator whose saved photo was flagged too unclear to cast (render_ad says so): true casts the current photo as it is, no new image needed",
      "type": "boolean"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the creator id (from list_creators)"
    }
  },
  "required": [
    "id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "domain": {
      "description": "website domain",
      "type": "string"
    },
    "sells": {
      "description": "what the brand sells",
      "type": "string"
    },
    "summary": {
      "description": "one-line description",
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "audience": {
      "type": "string"
    },
    "positioning": {
      "type": "string"
    },
    "voice": {
      "description": "brand voice/tone",
      "type": "string"
    },
    "style": {
      "description": "visual style — palette, typography, aesthetic",
      "type": "string"
    },
    "goal": {
      "description": "current marketing goal",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "the store key to read (one of the allowlisted keys)"
    },
    "limit": {
      "description": "max array items to return (default 50)",
      "type": "number"
    }
  },
  "required": [
    "key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "language": {
      "description": "language for generated ads, copy and answers — e.g. \"English\", \"German\", \"Japanese\"",
      "type": "string"
    },
    "theme": {
      "description": "app appearance",
      "type": "string",
      "enum": [
        "dark",
        "light"
      ]
    },
    "watchEmail": {
      "description": "weekly competitor-watch email on/off",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "tiktok",
        "x",
        "youtube",
        "threads",
        "bluesky",
        "telegram",
        "reddit",
        "pinterest",
        "instagram",
        "meta",
        "google_ads",
        "linkedin",
        "pinterest_ads",
        "linkedin_ads",
        "reddit_ads",
        "apple_ads",
        "microsoft_ads",
        "google_business",
        "google_analytics",
        "snapchat_ads",
        "x_ads",
        "tiktok_ads",
        "google_tag_manager",
        "google_search_console",
        "bing_webmaster"
      ],
      "description": "which connector’s accounts to list"
    }
  },
  "required": [
    "provider"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "enum": [
        "tiktok",
        "x",
        "youtube",
        "threads",
        "bluesky",
        "telegram",
        "reddit",
        "pinterest",
        "instagram",
        "meta",
        "google_ads",
        "linkedin",
        "pinterest_ads",
        "linkedin_ads",
        "reddit_ads",
        "apple_ads",
        "microsoft_ads",
        "google_business",
        "google_analytics",
        "snapchat_ads",
        "x_ads",
        "tiktok_ads",
        "google_tag_manager",
        "google_search_console",
        "bing_webmaster"
      ],
      "description": "which connector to scope"
    },
    "accountIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "the ids (from list_connector_accounts) this brand may use — an empty array shares nothing"
    }
  },
  "required": [
    "provider",
    "accountIds"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "description": "provider id exactly as list_connectors reports it, e.g. \"meta\", \"google_ads\", \"youtube\", \"linkedin\""
    },
    "confirm": {
      "description": "REQUIRED true — reconnecting a sign-in account afterwards needs the user's browser; a paste-a-key account is reconnected with connect_connector",
      "type": "boolean"
    },
    "account": {
      "description": "on a channel with several connected accounts (TikTok, X, YouTube, Threads, Bluesky, Telegram, Reddit, Pinterest): remove ONLY this account (@handle or id from list_connector_accounts) and keep the others",
      "type": "string"
    }
  },
  "required": [
    "provider"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "description": "the connector id: stripe, openai_ads, apple_ads, bluesky, telegram, bing_webmaster, posthog, mixpanel, amplitude, slack, discord, webhook"
    },
    "fields": {
      "description": "that provider's own field names and values, e.g. {\"apiKey\":\"…\"}; the names for each provider are in the description",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "required": [
    "provider"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "description": "provider id exactly as list_connectors reports it, e.g. \"linkedin\", \"tiktok_ads\", \"meta\""
    }
  },
  "required": [
    "provider"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "the invitee’s email"
    },
    "role": {
      "description": "default member",
      "type": "string",
      "enum": [
        "member",
        "admin"
      ]
    },
    "confirm": {
      "description": "REQUIRED true — this invites a real person",
      "type": "boolean"
    }
  },
  "required": [
    "email"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "the member’s email"
    },
    "confirm": {
      "description": "REQUIRED true",
      "type": "boolean"
    }
  },
  "required": [
    "email"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "the member’s email"
    },
    "role": {
      "type": "string",
      "enum": [
        "admin",
        "member"
      ],
      "description": "the new role"
    },
    "confirm": {
      "description": "REQUIRED true",
      "type": "boolean"
    }
  },
  "required": [
    "email",
    "role"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "kind": {
      "description": "'ours' = a defect; 'user' = a refusal we authored; 'unknown' = we could not tell",
      "type": "string",
      "enum": [
        "ours",
        "user",
        "unknown"
      ]
    },
    "surface": {
      "description": "where it happened: http (an API route), mcp (an agent tool), agent (the in-app Studio agent), job (an async render/publish), client (a browser crash)",
      "type": "string",
      "enum": [
        "http",
        "mcp",
        "agent",
        "job",
        "client"
      ]
    },
    "since": {
      "description": "ISO timestamp — only groups last seen at or after this",
      "type": "string"
    },
    "limit": {
      "description": "how many groups to return (default 50, max 200)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "fingerprint": {
      "type": "string",
      "description": "the `fp` value from list_errors"
    }
  },
  "required": [
    "fingerprint"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "the brand domain, e.g. flourish.com"
    },
    "mode": {
      "description": "'competitors' (default, excludes the searched company), 'inspiration' (best relevant ads incl. it), or 'company'",
      "type": "string",
      "enum": [
        "competitors",
        "inspiration",
        "company"
      ]
    }
  },
  "required": [
    "domain"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "companyName": {
      "description": "the advertiser name",
      "type": "string"
    },
    "domain": {
      "description": "the advertiser domain",
      "type": "string"
    },
    "country": {
      "description": "2-letter, default 'US'",
      "type": "string"
    },
    "limit": {
      "description": "max ads per platform (default 30)",
      "type": "number"
    },
    "sort": {
      "description": "'longest_running' (default) etc.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "competitors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "the brand name, as it advertises"
          },
          "domain": {
            "description": "its domain, e.g. ridge.com — required for Google Ads Transparency, and what disambiguates a common brand name on Meta",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": {}
      },
      "description": "the brands to watch — the COMPLETE list, replacing whatever was set before. Empty array = stop watching."
    },
    "runNow": {
      "description": "true to run one check immediately (spends credits now) instead of waiting a week for the first one",
      "type": "boolean"
    }
  },
  "required": [
    "competitors"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "competitor": {
      "description": "only findings for this watched brand (exact name as returned in `watching`) — omit for all of them",
      "type": "string"
    },
    "limit": {
      "description": "max findings to return (default 25, max 75 — the server keeps at most 75, and at most 15 per brand)",
      "type": "number"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "what to research, e.g. \"the longest-running protein-pancake ads on Meta\""
    },
    "brand": {
      "description": "brand name or profile object to tailor the research to; omit to use the workspace’s saved brand",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {},
          "additionalProperties": {}
        }
      ]
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "description": "keyword search across ALL advertisers (use INSTEAD of companyName/pageId)",
      "type": "string"
    },
    "companyName": {
      "description": "one advertiser’s ads by brand name",
      "type": "string"
    },
    "pageId": {
      "description": "one advertiser’s ads by Facebook page id (most precise)",
      "type": "string"
    },
    "country": {
      "description": "2-letter code or 'ALL' (default ALL)",
      "type": "string"
    },
    "status": {
      "description": "ACTIVE = currently running; default ALL (includes proven past winners)",
      "type": "string",
      "enum": [
        "ACTIVE",
        "INACTIVE",
        "ALL"
      ]
    },
    "mediaType": {
      "description": "filter by creative type (default ALL)",
      "type": "string",
      "enum": [
        "ALL",
        "IMAGE",
        "VIDEO",
        "MEME",
        "IMAGE_AND_MEME",
        "NONE"
      ]
    },
    "limit": {
      "description": "max ads returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "domain": {
      "description": "the advertiser's domain, e.g. nike.com",
      "type": "string"
    },
    "advertiserId": {
      "description": "Google advertiser id (AR…) when the domain is ambiguous",
      "type": "string"
    },
    "region": {
      "description": "2-letter region, default US",
      "type": "string"
    },
    "limit": {
      "description": "max ads returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "company": {
      "description": "advertiser company name",
      "type": "string"
    },
    "keyword": {
      "description": "keyword across all advertisers",
      "type": "string"
    },
    "companyId": {
      "description": "LinkedIn company id (numeric) when the name is ambiguous",
      "type": "string"
    },
    "countries": {
      "description": "CSV of 2-letter codes like 'US,CA'; omit or 'ALL' = worldwide",
      "type": "string"
    },
    "limit": {
      "description": "max ads returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "description": "product category, topic or hashtag — \"calorie tracker app\", \"matcha\", \"#cleanbeauty\""
    },
    "platforms": {
      "description": "default all three",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "tiktok",
          "instagram",
          "youtube"
        ]
      }
    },
    "limit": {
      "description": "creators to return, 1–30 (default 12)",
      "type": "number"
    },
    "queries": {
      "description": "query variants per platform, 1–4 (default 3); each is a paid search call",
      "type": "number"
    },
    "minAvgViews": {
      "type": "number"
    },
    "minEngagement": {
      "description": "interactions per view, 0–1 (0.05 = 5%)",
      "type": "number"
    },
    "enrich": {
      "description": "read follower counts for the top 6 (default true, ~1 credit each)",
      "type": "boolean"
    },
    "marketplace": {
      "description": "also search Instagram’s creator marketplace (Meta’s own creator directory, free) for the same niche; needs the Meta connector",
      "type": "boolean"
    }
  },
  "required": [
    "niche"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "subject, brand, product or hashtag — \"liquid death\", \"coffee\", \"#homecafe\""
    },
    "platforms": {
      "description": "default all three",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "tiktok",
          "instagram",
          "youtube"
        ]
      }
    },
    "limit": {
      "description": "posts per platform, 1–60 (default 24)",
      "type": "number"
    },
    "queries": {
      "description": "query variants per platform, 1–4 (default 1); each is a paid search call",
      "type": "number"
    }
  },
  "required": [
    "topic"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "keyword or hashtag (no # needed)"
    },
    "limit": {
      "description": "max videos returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "keyword to search reels for"
    },
    "limit": {
      "description": "max reels returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "keyword to search videos for"
    },
    "limit": {
      "description": "max videos returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "what to search Reddit for"
    },
    "limit": {
      "description": "max posts returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "keyword to search Threads for"
    },
    "limit": {
      "description": "max posts returned (1–25, default 8)",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "exact endpoint path, e.g. '/v1/tiktok/profile' — non-allowlisted paths are rejected"
    },
    "params": {
      "description": "endpoint query params, e.g. {handle:'nike'}",
      "type": "object",
      "properties": {},
      "additionalProperties": {}
    }
  },
  "required": [
    "path"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}