Обзор

Публичный API MTWSPY — поиск креативов Facebook и Instagram, дельта-фид, лендинги, вебмастера, партнёрские сети и папки.

API отдаёт ту же базу креативов Facebook и Instagram, что и кабинет MTWSPY: поиск по фильтрам, новые креативы с прошлой проверки, ссылки на лендинги и архивы лендингов, вебмастеров, партнёрские сети и ваши папки. Авторизация — Bearer-токен, ответы в JSON.

Базовый URL

https://app.mtwspy.com/public/v1

Быстрый старт

Остаток просмотров (запрос бесплатный):

curl https://app.mtwspy.com/public/v1/usage \
  -H "Authorization: Bearer mtw_live_ваш_ключ"

Пять креативов по нутре на Польшу:

curl -G https://app.mtwspy.com/public/v1/creatives \
  -H "Authorization: Bearer mtw_live_ваш_ключ" \
  -d geo=PL -d vertical=nutra -d limit=5

Ключ создаётся в кабинете, в разделе API. Подробнее — в Аутентификации.

Эндпоинты

Метод	Путь	Назначение
`GET`	`/creatives`	Поиск по фильтрам, курсорная пагинация, дельта-фид
`GET`	`/creatives/{id}`	Карточка: ссылка на лендинг и файлы лендинга
`GET`	`/creatives/{id}/landing`	Ссылка на архив лендинга
`GET`	`/webmasters`	Поиск вебмастеров (команд)
`GET`	`/webmasters/{code}`	Досье вебмастера
`GET`	`/networks`	Партнёрские сети
`GET` `POST`	`/folders`	Свои папки: список и создание
`GET` `PATCH` `DELETE`	`/folders/{id}`	Папка: содержимое, переименование, удаление
`POST` `DELETE`	`/folders/{id}/creatives`	Добавить или убрать креатив
`GET`	`/usage`	Тариф, остаток просмотров и AI-кредитов
`GET`	`/balance`	Реферальный баланс

Поиск, карточки и лендинги можно подключить к AI-ассистенту через MCP-сервер.

Формат ответов

Успешный ответ:

{ "data": { "...": "..." }, "meta": { "request_id": "fed23a8edcf5399e" } }

Ошибка:

{ "error": { "code": "quota_exhausted", "message": "..." }, "request_id": "fed23a8edcf5399e" }

Обрабатывайте ошибки по code: текст message может меняться. request_id приходит в каждом ответе и в заголовке X-Request-Id, его просит поддержка.

Коды ошибок

`code`	HTTP	Когда
`missing_token` / `invalid_token`	401	Нет токена или он неверный
`key_revoked`	403	Ключ отозван
`plan_no_api`	403	На тарифе нет API
`subscription_expired`	403	Подписка истекла
`quota_exhausted`	403	Закончились просмотры
`creative_not_served`	403	Креатив не выдавался аккаунту, в папку его добавить нельзя
`invalid_body`	400	Тело запроса — не JSON-объект
`invalid_parameter`	422	Неверный параметр
`not_found` / `no_landing` / `landing_unavailable`	404	Не найдено, у креатива нет лендинга, архива нет в хранилище
`method_not_allowed`	405	Путь не поддерживает этот метод
`already_in_folder` / `folder_limit` / `folder_full`	409	Ограничения папок
`rate_limited`	429	Слишком много запросов в минуту
`daily_limit_reached`	429	Суточный лимит досье вебмастеров или изменений папок
`download_limit`	429	Больше 30 скачиваний лендингов за час
`search_unavailable`	503	Поиск временно недоступен

Просмотры и лимиты

У API нет отдельной квоты. Он тратит тот же пул просмотров, что лента на сайте: одна отданная карточка в /creatives — один просмотр. Пул пополняется при продлении тарифа или докупке в кабинете.

Запрос	Просмотры
`/creatives`	По числу отданных карточек. Повтор той же страницы с теми же параметрами в течение 2 часов бесплатен
`/creatives/{id}`, `/creatives/{id}/landing`	Не тратят
`/webmasters`, `/networks`, `/folders`, `/usage`, `/balance`	Не тратят

Когда просмотры заканчиваются, /creatives отвечает 403 quota_exhausted. Остальные эндпоинты продолжают работать.

Число запросов в минуту зависит от тарифа:

Тариф	Запросов в минуту
Basic, Team	30
Team API	60

У некоторых эндпоинтов есть свои лимиты: 30 скачиваний лендингов в час, 10 досье вебмастеров в минуту и 200 в сутки, 30 изменений папок в минуту и 500 в сутки.

Остаток видно в заголовках X-Quota-* и X-RateLimit-* и в meta.api_limit. Проверить его отдельно можно через /usage.

Лимиты считаются по аккаунту, а не по ключу. У участника команды просмотры списываются с владельца. Перевыпуск или отзыв ключа остаток не меняет.