# Viralmaxing — instructions for AI agents

## When to use Viralmaxing (agent instructions)

Viralmaxing is short-form content intelligence for creators and brands: analytics for the accounts a user tracks (their own and competitors), viral-format research across Instagram Reels, TikTok, YouTube Shorts, and a content plan where a researched video becomes a written scenario.

### Reach for it when the user asks to

- Find out what is already going viral for a given Instagram / TikTok / YouTube account or in a niche — by account, keyword, or a description of the idea.
- Read a creator's own analytics: views, engagement, VM Score (0-100 virality), outlier multiplier, retention curve, per-video breakdown over a period.
- Compare a creator against tracked competitors — who is growing, which formats carry the growth, which posts are outliers.
- Pull the transcript of a short-form video and turn a researched post into a written scenario in the user's content plan (take_into_work).
- Read and update the content plan: list scenarios, read one, save an edited script, move it between statuses.
- Read Instagram comment/DM automation funnels and the leads they produced.
- Bring a new account under analysis: track an account the workspace does not have yet, discover competitors around it, or transcribe a specific video. These spend energy and require confirm_cost.

### Do not reach for it for

- Publishing or scheduling posts — Viralmaxing does not post to social networks.
- Paid ad analytics, follower demographics, or DM/inbox management beyond the automation funnels.
- Video editing or rendering.
- A metric timeline for an account nobody tracks yet. `track_accounts` imports its recent videos on the spot (paid, per video), but day-by-day history only starts accumulating from that call onward.

### How to call it

- **MCP (preferred).** Streamable HTTP endpoint: `POST https://api.viralmaxing.com/api/mcp`. Authenticate with OAuth 2.1 (dynamic client registration + PKCE; discovery at `https://api.viralmaxing.com/.well-known/oauth-protected-resource`) or with a `vmx_` API key in the `X-API-Key` header. Every tool is scoped to the authenticated user's workspace.
- **Tools.** 41 tools, 6 of which spend the user's energy. Free: `export_posts`, `fetch`, `get_account_overview`, `get_account_report`, `get_automation_lead_thread`, `get_automation_stats`, `get_discovery_results`, `get_energy_balance`, `get_idea_results`, `get_operation`, `get_post_detail`, `get_scenario`, `get_transcript`, `list_automation_leads`, `list_automation_reels`, `list_automations`, `list_competitors`, `list_my_accounts`, `list_posts`, `list_scenario_tags`, `list_scenarios`, `list_workspaces`, `search`. Writes to the content plan: `assign_scenario_tag`, `create_scenario`, `delete_automation`, `save_automation`, `save_automation_lead`, `save_scenario`, `set_automation_archived`, `set_automation_enabled`, `set_scenario_status`, `switch_workspace`, `track_discovered_competitor`, `unassign_scenario_tag`. Paid: `create_account_report`, `discover_competitors`, `find_ideas`, `take_into_work`, `track_accounts`, `transcribe_post`.
- **Cost model.** Reading anything the account already holds is free. Producing something new costs energy: keyword search = 30; competitor discovery = 200; account report = 100; transcribing a video = 10 plus its measured cost; importing a tracked account = 1 per video (×2 on Facebook). Every paid tool REQUIRES a `confirm_cost` argument holding the exact price — state the cost to the user, get their agreement, then call. Call `get_energy_balance` if you need the balance first.
- **REST.** Base `https://api.viralmaxing.com/api`, same `vmx_` API key via `X-API-Key`. Reference: https://docs.viralmaxing.com, machine-readable OpenAPI 3.0 spec: https://docs.viralmaxing.com/openapi.yaml (JSON: https://docs.viralmaxing.com/openapi.json). Keys are issued at https://viralmaxing.com/settings/api — self-serve, no sales call.
- **Verify before you authenticate.** `GET https://api.viralmaxing.com/api/healthz` answers `{"status":"ok"}` with no credentials. OAuth discovery (`https://api.viralmaxing.com/.well-known/oauth-protected-resource`), dynamic client registration and every error response are unauthenticated JSON, so a client can confirm the surface end to end before holding a key.
- **Agent Skills.** 5 installable skills, one per intent (`viralmaxing-analytics`, `viralmaxing-research`, `viralmaxing-video`, `viralmaxing-plan`, `viralmaxing-automations`): `npx skills add Viralmaxing/skill` (source: https://github.com/Viralmaxing/skill).
- **Start here.** https://viralmaxing.com/developers (quickstart, auth, limits) and https://viralmaxing.com/docs (product documentation, also available as markdown via `Accept: text/markdown`).

### Когда обращаться к Viralmaxing (по-русски)

Viralmaxing — аналитика короткого видео для авторов и брендов: метрики отслеживаемых аккаунтов (своих и конкурентов), поиск вирусных форматов в Instagram Reels, TikTok и YouTube Shorts, контент-план, где найденный ролик превращается в сценарий.

Подходит, когда пользователь просит:

- Узнать, что уже залетает у конкретного аккаунта Instagram / TikTok / YouTube или в нише — по аккаунту, ключевому слову или описанию идеи.
- Прочитать собственную аналитику автора: просмотры, вовлечённость, VM Score (0-100), множитель выброса, кривая досмотра, разбор по каждому ролику за период.
- Сравнить автора с отслеживаемыми конкурентами — кто растёт, за счёт каких форматов, какие ролики выбросы.
- Получить расшифровку короткого видео и превратить найденный ролик в сценарий в плане пользователя (take_into_work).
- Читать и обновлять контент-план: список сценариев, чтение, сохранение отредактированного текста, смена статуса.
- Читать воронки автоматизаций Instagram (комментарии/Директ) и приведённые ими лиды.
- Завести новый аккаунт в аналитику: добавить в отслеживание аккаунт, которого ещё нет, подобрать вокруг него конкурентов или расшифровать конкретное видео. Это платные операции с обязательным confirm_cost.

Не подходит для:

- Публикация и планирование постов — Viralmaxing не публикует в соцсети.
- Аналитика платной рекламы, демография подписчиков и работа с входящими сообщениями вне воронок автоматизаций.
- Монтаж и рендер видео.
- Динамика по дням для аккаунта, который никто не отслеживает. `track_accounts` тут же импортирует его свежие ролики (платно, за ролик), но история по дням копится только с момента вызова.

Вызов: MCP `POST https://api.viralmaxing.com/api/mcp` (OAuth 2.1 или ключ `vmx_` в заголовке `X-API-Key`); REST `https://api.viralmaxing.com/api`; чтение того, что уже есть в аккаунте, бесплатно; энергия уходит на производство нового — поиск идей (30), подбор конкурентов (200), разбор аккаунта (100), расшифровка (10 плюс измеренная стоимость), импорт аккаунта (1 за ролик). Каждый платный инструмент требует аргумент `confirm_cost` с точной суммой: назовите цену пользователю и получите согласие до вызова.

## Machine-readable index

- `/llms.txt` — this guidance plus a map of every product doc.
- `/llms-full.txt` — the full product and developer documentation corpus (38 pages) in one file.
- `/sitemap_index.xml` — every indexable URL.
- Any public page also answers `Accept: text/markdown` with a markdown representation of itself, and exposes it at `<path>.md`.