# Hermoso developer documentation

> Hermoso is an AI marketing studio that an AI agent can drive end to end: research the ads already
> running in a market, generate finished image and video ads, publish them to the brand's own social
> channels, and build and manage the paid campaigns behind them.

> The interface is an MCP server exposing 681 tools, available hosted at https://app.hermoso.ai/mcp and over stdio
> via `npx -y hermoso mcp`. Authentication is an agent key sent as `Authorization: Bearer hmk_...`.
> There is no public REST API today.

## Documentation
- [Overview](https://hermoso.ai/docs/)
- [Quickstart](https://hermoso.ai/docs/quickstart/)
- [MCP server](https://hermoso.ai/docs/mcp/)
- [CLI](https://hermoso.ai/docs/cli/)
- [Skills](https://hermoso.ai/docs/skills/)
- [Connectors](https://hermoso.ai/docs/connectors/)
- [Jobs & idempotency](https://hermoso.ai/docs/jobs/)
- [Credits & costs](https://hermoso.ai/docs/credits/)
- [Errors](https://hermoso.ai/docs/errors/)
- [All tools](https://hermoso.ai/docs/reference/)
- [Ad spy & research](https://hermoso.ai/docs/reference/research/)
- [Creative generation](https://hermoso.ai/docs/reference/create/)
- [Publishing & scheduling](https://hermoso.ai/docs/reference/publish/)
- [Ad campaign management](https://hermoso.ai/docs/reference/ads/)
- [Files & documents](https://hermoso.ai/docs/reference/files/)
- [Workspace & account](https://hermoso.ai/docs/reference/workspace/)

## Machine-readable
- [Tool index, with full JSON Schema for every parameter](https://hermoso.ai/docs/reference/tools.json)
- [Site-wide summary](https://hermoso.ai/llms.txt)

## Connectors
- Meta (`meta`): Post to Facebook & Instagram, build and run ad campaigns with full targeting and audiences, collect leads with instant forms, read how posts and ads performed, and reply to or hide comments. A published Instagram post can be deleted but never edited — Meta allows no change to it at all.
- Google Ads (`google_ads`): Campaigns, budgets and reporting for Google Ads. New campaigns start paused, so nothing spends until you enable them.
- Microsoft Ads (`microsoft_ads`): Campaigns, ad groups, search ads, keywords, budgets and reporting on Bing. Everything starts paused, so nothing spends until you activate it.
- Telegram (`telegram`): Post to a channel, group or chat as your own bot. 4096 characters of text, 1024 with media. Telegram cannot list a bot’s chats, so you name the destination.
- Bluesky (`bluesky`): Post as your account — text up to 300 characters, plus EITHER up to 4 images OR one MP4 video, never both. Links are made clickable for you. Video needs a confirmed email on your Bluesky account.
- Apple Ads (`apple_ads`): App Store search ads and Ads on Apple Maps, all created PAUSED. An App Store ad renders from your App Store Connect product page, not an image you upload; a Maps brand ad uses your own image and copy.
- ChatGPT Ads (`openai_ads`): Ads inside ChatGPT — the sponsored card under an answer. Campaigns, budgets and reporting; one format only, a text + image card, no video. Everything starts paused.
- Threads (`threads`): Publish text, image or video posts, repost anyone, read how they performed, reply to and hide replies, search Threads, and delete a post. Threads has no edit — only delete and repost.
- YouTube (`youtube`): Publish videos to your channel — public, unlisted or private — then read performance and reply to comments.
- TikTok (`tiktok`): Publish a video or a photo post (up to 35 images) — live, or into drafts. Read back how each one did. TikTok’s API can’t delete or edit a post once it’s up; that’s done in their app.
- LinkedIn (`linkedin`): Post to a company Page or your profile, and run LinkedIn ad campaigns. Which identities this brand may act as is yours to choose — your profile is off unless you turn it on.
- X (Twitter) (`x`): Post, thread, poll or reply, and read performance and mentions. X charges per API call, so every action costs a few credits.
- Snapchat (`snapchat`): Publish a finished video to your Public Profile as a Story or a Spotlight, and group Snaps into a Saved Story. Video only — 5–60s for a Story, 6–60s for a Spotlight, 540x960 minimum. NOT OFFERED YET: Snapchat posting is NOT BUILT — there are no Story, Spotlight or Saved Story tools or routes in Hermoso, only an OAuth descriptor. Snap has also not allowlisted this app for the Public Profile API (their own words: "The Public Profile API is currently allowlist only"), so BOTH the code and the access are outstanding. Snapchat ADS is a separate connector and is fully built and live.
- Reddit (`reddit`): Post to a subreddit, read and answer the comments, edit a text post’s body or delete it. One subreddit at a time — Reddit bans cross-posting. Titles can never be edited. NOT OFFERED YET: Reddit has not approved API access for this app yet (approval ticket, not a credential).
- TikTok Ads (`tiktok_ads`): TikTok ad campaigns, budgets and reporting. Everything starts paused — nothing spends until you say so.
- Snapchat Ads (`snapchat_ads`): Snapchat campaigns, ad squads, budgets and performance. Everything starts paused, so nothing spends until you say so. Headlines run up to 34 characters.
- Reddit Ads (`reddit_ads`): Reddit ad campaigns, ad groups, budgets and reporting. Everything starts paused, so nothing spends until you say so.
- X Ads (`x_ads`): X (Twitter) campaigns, line items, promoted posts, targeting and reporting. Everything starts paused, so nothing spends until you say so.
- Pinterest (`pinterest`): Publish image and video Pins to a board you pick, edit or delete Pins and boards afterwards, and read how each one did.
- Pinterest Ads (`pinterest_ads`): Pinterest campaigns, ad groups, budgets and reporting, promoting Pins that are already live. Everything starts paused, so nothing spends until you say so.
- Google Business Profile (`google_business`): Post updates, events and offers to your Google Search & Maps listing, and read the calls, clicks and directions they drive. NOT OFFERED YET: Google has not allowlisted the Business Profile API for this project yet — every Business Profile API reads 0 QPM, so locations, insights and Q&A 403 alongside posting and reviews.
- Google Analytics (`google_analytics`): GA4 traffic, conversions and realtime activity by channel, campaign or landing page, plus key events and custom dimensions. GA4 only. Only properties you tick under Manage accounts are readable.
- Google Tag Manager (`google_tag_manager`): Your site’s analytics and conversion tags. Audit what is already live, stage new ones, and publish when you say so — staging never goes live on its own. Google rate-limits this API hard, so reads are deliberately unhurried. NOT OFFERED YET: GOOGLE_TAG_MANAGER_SCOPE_DECLARED is unset in THIS environment. Note this is no longer a paperwork blocker: all three Tag Manager scopes — `tagmanager.edit.containers` (read + stage), `tagmanager.edit.containerversions` (turn a workspace into a version) and `tagmanager.publish` (make that version live) — are declared on the consent screen and were APPROVED by Google OAuth verification on 2026-08-20 for project 209678518568. They are SENSITIVE (measured 2026-08-19), which is why that submission was needed; approval makes them usable, not non-sensitive.
- Google Search Console (`google_search_console`): Impressions, clicks, CTR and position for the organic traffic Google sends you — the one place real search terms still exist. Plus live index status per page, and sitemap submit/remove. NOT OFFERED YET: GOOGLE_SEARCH_CONSOLE_SCOPE_DECLARED is unset, so the connector is held back even though the `webmasters` scope is now declared on the consent screen (2026-08-19).
- Bing Webmaster Tools (`bing_webmaster`): Bing search terms, clicks and position, crawl issues and inbound links — plus keyword research with real impression volumes and no ad spend. Bing also feeds Copilot.
- PostHog (`posthog`): Per-user funnels, retention and session replay — the questions GA4 cannot answer. Replays come back as links you open in PostHog.
- Mixpanel (`mixpanel`): Retention cohorts, event breakdowns and the events a project actually records — plus any saved Mixpanel report, read straight back by its id.
- Amplitude (`amplitude`): Event segmentation, funnels with a conversion window, retention curves, and one person’s full activity stream — found by user id, device id or just the start of one.
- Google Drive (`google_drive`): One connection for Drive, Sheets and Docs — pull files into the composer, save renders back, build reports and briefs. Hermoso only ever sees the files you pick in the Google picker.
- OneDrive (`microsoft_onedrive`): Save finished renders into OneDrive, and organize them into folders.
- Slack (`slack`): A message in your channel the moment a render finishes or fails.
- Discord (`discord`): A ping in your server every time a render finishes or fails.
- Webhook (`webhook`): POST a JSON event to any URL — Zapier, Make, n8n — when a render finishes.
- Custom MCP (`mcp`): Tools from any MCP server you run become live tools for the Studio agent.