API папок — сохранение креативов в папки MTWSPY

GET, POST, PATCH, DELETE /folders — список своих папок, создание, переименование и удаление, добавление и удаление креативов.

Папки те же, что в разделе Папки кабинета: созданное через API сразу видно на сайте и наоборот.

Метод	Путь	Назначение
`GET`	`/folders`	Список своих папок
`POST`	`/folders`	Создать папку
`GET`	`/folders/{id}`	Папка и id креативов в ней
`PATCH`	`/folders/{id}`	Переименовать, сменить цвет или иконку
`DELETE`	`/folders/{id}`	Удалить папку
`POST`	`/folders/{id}/creatives`	Добавить креатив
`DELETE`	`/folders/{id}/creatives/{creative_id}`	Убрать креатив

Только свои папки, бесплатно

API видит и меняет только папки владельца ключа. Командные папки коллег недоступны, чужая папка отвечает 404, как несуществующая. Просмотры папки не тратят.

Тело запросов POST и PATCH — JSON с заголовком Content-Type: application/json (form-urlencoded тоже принимается).

Список папок

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

{
  "data": [
    {
      "id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21",
      "name": "MX nutra hooks",
      "color": "#3b82f6",
      "icon": "🎯",
      "privacy": "private",
      "creatives_count": 12,
      "created_at": "2026-11-09T12:00:00+03:00"
    }
  ],
  "meta": { "charged": 0 }
}

Поле	Описание
`id`	uuid папки — подставляется в пути `/folders/{id}`
`privacy`	`private`, `public` (по ссылке) или `team` (видна команде). Меняется только в кабинете
`creatives_count`	Сколько креативов в папке

Создать папку

curl -X POST https://app.mtwspy.com/public/v1/folders \
  -H "Authorization: Bearer mtw_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"name": "MX nutra hooks", "color": "#3b82f6", "icon": "🎯"}'

Поле	Значения
`name`	Обязательно. 1–50 символов, без HTML
`color`	`#22c55e` (по умолч.), `#3b82f6`, `#f59e0b`, `#ef4444`, `#8b5cf6`, `#ec4899`
`icon`	`📁` (по умолч.), `🎯`, `⭐`, `🚀`, `💼`, `📊`

Папка создаётся приватной. В ответе — объект папки. На пользователя — до 100 папок.

Папка и её содержимое

curl https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21 \
  -H "Authorization: Bearer mtw_live_ваш_ключ"

Ответ — объект папки и creative_ids: id креативов, последние добавленные первыми (до 1000). Карточки креативов здесь не отдаются — их открывают через /creatives/{id}.

{
  "data": {
    "id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21",
    "name": "MX nutra hooks",
    "...": "...",
    "creative_ids": [48211773, 48190455]
  }
}

Переименовать

curl -X PATCH https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21 \
  -H "Authorization: Bearer mtw_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"name": "MX nutra — top"}'

Передайте любые из полей name, color, icon — остальные не изменятся.

Удалить папку

curl -X DELETE https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21 \
  -H "Authorization: Bearer mtw_live_ваш_ключ"

Удаляет папку, её содержимое и теги. Сами креативы в базе остаются. Действие не отменяется.

{ "data": { "id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21", "deleted": true } }

Добавить креатив в папку

curl -X POST https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21/creatives \
  -H "Authorization: Bearer mtw_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"creative_id": 48211773}'

{ "data": { "folder_id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21", "creative_id": 48211773, "added": true } }

Добавлять можно креативы, которые ваш аккаунт уже получил через /creatives или /creatives/{id} за последние 7 дней. В одной папке через API — до 1000 креативов.

Убрать креатив из папки

curl -X DELETE https://app.mtwspy.com/public/v1/folders/6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21/creatives/48211773 \
  -H "Authorization: Bearer mtw_live_ваш_ключ"

{ "data": { "folder_id": "6f1c2a90-3b1e-4c8d-9a52-1e0f7b6c4d21", "creative_id": 48211773, "removed": true } }

Query-формы

Если клиенту удобнее передавать id параметрами:

Путь	Query-форма
`/folders/{id}`	`/folder?id={id}`
`/folders/{id}/creatives`	`/folder_creatives?folder_id={id}`
`/folders/{id}/creatives/{creative_id}`	`/folder_creatives?folder_id={id}&creative_id={creative_id}`

Лимиты

Создание, изменение, удаление папок и любые изменения их содержимого вместе — не больше 30 в минуту и 500 за сутки на аккаунт. Чтение — в пределах общего rate-limit ключа.

Ошибки

`code`	HTTP	Когда
`invalid_parameter`	422	Неверный uuid папки, id креатива, имя, цвет или иконка
`invalid_body`	400	Тело с `Content-Type: application/json` не разбирается как JSON-объект
`not_found`	404	Папки нет или она чужая; креатива нет в базе или в папке
`folder_limit`	409	Уже 100 папок
`already_in_folder`	409	Креатив уже в папке
`folder_full`	409	В папке 1000 креативов
`creative_not_served`	403	Креатив не выдавался вашему аккаунту через API
`method_not_allowed`	405	Метод не поддерживается этим путём
`rate_limited`	429	Больше 30 изменений в минуту или общий rate-limit
`daily_limit_reached`	429	500 изменений за сутки

Папки

On this page