# MassFarmer GraphQL API — полная справка для LLM

> Версия генерируется из публичного белого списка API. Без внутренней инфраструктуры и чувствительных полей.

## Аутентификация

1. Создайте API-ключ: https://massfarmer.com/dashboard/account/api (префикс `sk_live_`)
2. Заголовки каждого запроса:
   - `X-API-KEY: <ваш-ключ>`
   - `X-TEAM-ID: <uuid-команды>` (из URL дашборда `/dashboard/{orgSlug}/{teamId}/…`)

Файлы cookie и браузерная сессия для этого API **не используются**.

## Адрес

```
POST https://massfarmer.com/api/graphql
Content-Type: application/json
```

## Пример запроса

```graphql
query {
  allProfiles(first: 5) {
    nodes {
      rowId
      name
      error
    }
  }
}
```

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-TEAM-ID: YOUR_TEAM_ID" \
  -d '{"query":"query { allProfiles(first: 5) { nodes { rowId name } } }"}' \
  https://massfarmer.com/api/graphql
```

## Идентификаторы

- `rowId` (UUID) — основной ключ для мутаций `*ByRowId`
- `id` (ID) — непрозрачный GraphQL Global ID для `node(id:)` и подключений `Relay`

## Типовой сценарий

1. `allProfiles` — список профилей
2. `createProfiles` → `startProfiles`; даже один UUID передаётся массивом
3. `createFile` (опционально) → `createAutomationTasks`
4. `retryAutomationTasks` по массиву UUID MassFarmer при ошибке
5. `cloudOperationBatch` — состояние массового выполнения

## Запросы

### Запрос: `allAccounts`

Список аккаунтов команды. Аргументы: `first`/`after`, `filter`, `orderBy`.
### Запрос: `allProfiles`

Список облачных профилей команды. Типичная первая операция — см. «Быстрый старт» в документации.
### Запрос: `allTasks`

Задачи автоматизации команды с фильтрацией и сортировкой.
### Запрос: `allAutoTasks`

Расписания автоматизаций команды.
### Запрос: `allAutomations`

Каталог автоматизаций (глобальный справочник, только чтение).
### Запрос: `allFiles`

Медиафайлы команды.
### Запрос: `allProxies`

Прокси команды.
### Запрос: `allServices`

Каталог платформ.
### Запрос: `allPlans`

Справочник планов.
### Запрос: `allLocations`

Справочник локаций.
### Запрос: `accountByRowId`

Один аккаунт по UUID `rowId`.
### Запрос: `profileByRowId`

Один профиль по UUID `rowId`.
### Запрос: `taskByRowId`

Одна задача по UUID `rowId`.
### Запрос: `autoTaskByRowId`

Одно расписание по UUID `rowId`.
### Запрос: `automationByRowId`

Одна запись каталога автоматизаций по `rowId`.
### Запрос: `fileByRowId`

Один файл по UUID `rowId`.
### Запрос: `proxyByRowId`

Один прокси по UUID `rowId`.
### Запрос: `serviceByRowId`

Одна платформа каталога по `rowId`.
### Запрос: `planByRowId`

Один план по `rowId`.
### Запрос: `locationByRowId`

Одна локация по `rowId`.
### Запрос: `node`

Загрузка объекта по непрозрачному GraphQL Global ID (`id`). Для прикладной логики предпочитайте `*ByRowId`.
### Запрос: `cloudOperationBatch`

Состояние массовой операции по UUID MassFarmer без идентификаторов облачной инфраструктуры.

## Мутации

### Мутация: `createProfiles`

Создать от 1 до 1000 облачных профилей одной идемпотентной операцией.
### Мутация: `createProxies`

Создать от 1 до 1000 прокси одной идемпотентной операцией.
### Мутация: `createAnalyticsAccounts`

Добавить аналитические аккаунты на платформах одной массовой операцией.
### Мутация: `createAutomationTasks`

Создать задачи одного сценария сразу для массива UUID профилей.
### Мутация: `createAutoTask`

Создать расписание автоматизации.
### Мутация: `createFile`

Загрузить видео в формате `base64` и создать запись файла.
### Мутация: `updateAutoTaskByRowId`

Обновить расписание по `rowId`.
### Мутация: `deleteAutoTaskByRowId`

Удалить расписание по `rowId`.
### Мутация: `deleteFileByRowId`

Удалить файл по `rowId`.
### Мутация: `startProfiles`

Запустить массив облачных профилей команды.
### Мутация: `stopProfiles`

Остановить массив облачных профилей команды.
### Мутация: `deleteProfiles`

Удалить массив облачных профилей команды.
### Мутация: `reinstallProfiles`

Переустановить массив облачных профилей с параметрами по UUID.
### Мутация: `refreshProfiles`

Обновить состояния массива профилей.
### Мутация: `refreshProfileLocations`

Обновить геопозиции массива профилей.
### Мутация: `setProfileLocations`

Изменить геопозиции массива профилей.
### Мутация: `cancelProfileReinstalls`

Отменить ещё не начавшиеся переустановки массива профилей.
### Мутация: `checkProxies`

Проверить массив прокси.
### Мутация: `updateProxiesBulk`

Обновить массив прокси с `patch`-объектами по UUID.
### Мутация: `deleteProxies`

Удалить массив прокси через массовую операцию.
### Мутация: `syncAnalyticsAccounts`

Синхронизировать аналитику массива аккаунтов.
### Мутация: `deleteAnalyticsAccounts`

Удалить массив аналитических аккаунтов.
### Мутация: `cancelAutomationTasks`

Отменить массив ожидающих или выполняющихся задач автоматизации по UUID MassFarmer.
### Мутация: `retryAutomationTasks`

Повторить массив завершившихся с ошибкой или отменённых задач по UUID MassFarmer.
### Мутация: `openProfileSessions`

Подготовить защищённые сессии для массива профилей.
### Мутация: `uniquizeFile`

Создать уникализированную копию видеофайла.

## Типы данных

### Account

Социальный аккаунт, привязанный к облачному профилю в рамках команды.

- `id`: Непрозрачный GraphQL Global ID для навигации по API (`node`, `connections`).
- `rowId`: Стабильный первичный ключ (UUID) — используйте в мутациях `*ByRowId`.
- `teamId`: Команда-владелец записи.
- `username`: Логин или идентификатор аккаунта на целевой платформе.
- `serviceId`: Ссылка на каталог платформы (TikTok и т.д.).
- `profileId`: Облачный профиль, на котором привязан аккаунт.
- `error`: Текст последней ошибки привязки или синхронизации.
- `errorAt`: Время фиксации ошибки.
- `serviceByServiceId`: Вложенный объект платформы из каталога.
- `profileByProfileId`: Профиль, к которому относится аккаунт.
### AutoTask

Расписание повторяющихся автоматизаций: интервал, лимит итераций, привязка к типу сценария.

- `id`: Непрозрачный GraphQL Global ID.
- `rowId`: UUID для CRUD через `*ByRowId`.
- `name`: Название расписания.
- `automationId`: Какая автоматизация запускается по расписанию.
- `intervalMin`: Минимальный интервал между запусками (минуты).
- `intervalMax`: Максимальный интервал (джиттер).
- `iteration`: Текущий номер итерации.
- `limit`: Максимум итераций (`null` — без лимита).
- `startedAt`: Время старта расписания.
- `lastRunAt`: Последний фактический запуск.
- `nextRunAt`: Следующий плановый запуск.
- `metadata`: Параметры сценария (JSON).
- `error`: Ошибка последнего цикла.
- `automationByAutomationId`: Каталожная автоматизация.
### Automation

Каталог доступных сценариев автоматизации (только чтение).

- `id`: Непрозрачный GraphQL Global ID.
- `rowId`: UUID каталожной записи.
- `name`: Название сценария.
- `type`: Совместимая текстовая категория сценария.
- `scenarioKey`: Стабильный ключ сценария MassFarmer.
- `kind`: Функциональная группа сценария.
- `serviceId`: Целевая платформа (TikTok и др.).
- `inputSchema`: Версионированная схема пользовательских параметров.
- `capabilities`: Нейтральные возможности сценария.
- `enabled`: Доступность сценария для запуска.
- `serviceByServiceId`: Платформа из каталога.
### File

Медиафайл команды. Загрузка через `createFile`: видео в формате `base64`, лимит около 100 МБ.

- `id`: Непрозрачный GraphQL Global ID.
- `rowId`: UUID файла в команде.
- `filename`: Имя файла.
- `mimeType`: MIME-тип (например, `video/mp4`).
- `sizeBytes`: Размер в байтах.
- `url`: URL доступа к файлу, если выдан.
- `signedUrl`: Временная подписанная ссылка.
- `duration`: Длительность видео (секунды).
- `metadata`: Метаданные обработки (JSON).
- `error`: Ошибка загрузки или обработки.
- `uploadedAt`: Время успешной загрузки.
- `expiresAt`: Срок действия подписанной ссылки.
### Location

Справочник геолокаций для профилей.

- `id`: Непрозрачный GraphQL Global ID.
- `rowId`: UUID локации.
- `key`: Ключ локации.
- `name`: Название региона или города.
### Plan

Справочник тарифных планов. Только чтение.

- `id`: Непрозрачный GraphQL Global ID.
- `rowId`: UUID плана.
- `key`: Ключ плана.
- `name`: Название плана.
### Profile

Облачный телефон: единица автоматизации команды. Центральный объект для задач, прокси и аккаунтов.

- `id`: Непрозрачный GraphQL Global ID.
- `rowId`: UUID первичного ключа — предпочтительный идентификатор в мутациях.
- `name`: Отображаемое имя профиля.
- `type`: Тип конфигурации устройства.
- `subType`: Подтип конфигурации.
- `version`: Версия образа или сборки профиля.
- `startedAt`: Когда профиль последний раз был запущен.
- `url`: Ссылка на удалённый доступ, если доступна.
- `proxyId`: Прикреплённый прокси.
- `locationId`: Справочная геолокация.
- `metadata`: Дополнительные настройки профиля (JSON).
- `gps`: Координаты GPS для эмуляции устройства.
- `paidUntil`: Дата окончания оплаченного периода устройства.
- `error`: Последняя ошибка жизненного цикла профиля.
- `tasksByProfileId`: Список задач на этом профиле.
- `accountsByProfileId`: Привязанные социальные аккаунты.
- `proxyByProxyId`: Данные прокси, если назначен.
### Proxy

Прокси для облачных профилей: поля `host`, `port` и `credentials`, статус и замена через `replaceProxy`.

- `id`: Непрозрачный GraphQL Global ID.
- `rowId`: UUID прокси.
- `host`: Хост прокси.
- `port`: Порт.
- `username`: Логин прокси.
- `type`: Тип прокси (например, `HTTP` или `SOCKS`).
- `status`: Состояние проверки и доступности.
- `ip`: Внешний IP, если известен.
- `metadata`: Дополнительные данные (JSON).
- `profilesByProxyId`: Профили, использующие этот прокси.
### Service

Справочник целевых платформ (логотип, ключ). Только чтение.

- `id`: Непрозрачный GraphQL Global ID.
- `rowId`: UUID платформы.
- `key`: Стабильный ключ (`slug`) платформы.
- `name`: Отображаемое имя.
- `logo`: URL логотипа.
### Task

Разовый запуск автоматизации на профиле: публикация, прогрев, вход и т.д. Создаётся вручную или из расписания.

- `id`: Непрозрачный GraphQL Global ID.
- `rowId`: UUID — ключ MassFarmer для управления задачей и её повтора.
- `name`: Человекочитаемое имя задачи.
- `status`: Статус выполнения (очередь, выполнение, успех, ошибка).
- `profileId`: Профиль, на котором выполняется задача.
- `automationId`: Тип автоматизации из каталога.
- `fileId`: Медиафайл для публикации, если нужен.
- `scheduleAt`: Отложенный старт (`Datetime`).
- `duration`: Длительность или лимит выполнения.
- `metadata`: Параметры сценария (JSON, схема зависит от `automation`).
- `images`: Дополнительные изображения (JSON).
- `logs`: Логи выполнения (JSON).
- `error`: Текст ошибки выполнения.
- `cancelledAt`: Момент отмены, если применимо.
- `profileByProfileId`: Связанный профиль.
- `automationByAutomationId`: Описание автоматизации.
- `fileByFileId`: Прикреплённый медиафайл.

## MCP (Apollo MCP Server)

- Локальный адрес: http://127.0.0.1:8000/mcp (`pnpm mcp:run`)
- MCP в рабочей среде: https://massfarmer.com/mcp
- Операции: белый список в `docs/reference/schema/mcp/operations/`
- Инструменты интроспекции: `search`, `validate`, `execute` (включены в конфигурации)

## Ссылки

- HTML-справка: https://massfarmer.com/api/docs
- Краткий индекс: https://massfarmer.com/api/llms.txt
- Условия: https://massfarmer.com/terms
- Поддержка: https://massfarmer.com/support