Обзор

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

API даёт программный доступ к базе рекламных креативов Facebook: поиск по фильтрам, дельта-фид новинок, ссылки на лендинги офферов и скачивание лендингов. Обычный REST — 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`	`/usage`	Остаток квоты и лимитов
`GET`	`/balance`	Реферальный баланс

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

Успех — конверт data + meta:

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

Ошибка — конверт error с машиночитаемым code (ориентируйтесь на него, не на текст):

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

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	Исчерпана месячная квота
`view_limit_exhausted`	403	Исчерпан пул открытий
`invalid_parameter`	422	Неверный параметр
`rate_limited`	429	Слишком часто
`download_limit`	429	>30 скачиваний лендингов в час
`not_found` / `no_landing`	404	Не найдено / нет лендинга
`search_unavailable`	503	Поиск временно недоступен

Лимиты

Три независимых ограничителя, все видны в заголовках ответа и в meta:

Лимит	Что	Team	Team API
`api_limit`	креативов/мес	10 000	50 000 (+overage $4/1000)
`basic_limit`	открытий карточек/мес	пул общий с интерфейсом сайта
rate-limit	запросов/мин	30	60

Поиск (/creatives) списывает api_limit по числу отданных объектов.
Открытие (/creatives/{id}) списывает api_limit + 1 и basic_limit + 1.
Скачивание лендинга не тратит квоту (свой лимит — 30/час).

Заголовки состояния: X-RateLimit-*, X-Quota-*, X-Basic-*. Проверить всё разом, не тратя квоту — /usage.

Квота считается по аккаунту, а не по ключу. Перевыпуск или отзыв ключа расход не обнуляет.