Введение

Управлять сегментами.
Управлять представителями.
Управлять аккаунтами и доступами.

Для использования API Яндекс.Аудиторий необходима авторизация с помощью OAuth-токена. Необходимо отправлять авторизационный токен в каждом запросе к API.

Для иллюстрации возможностей API в справочнике приведены примеры обращения к сервису. Методы в примерах возвращают демонстрационные данные, доступные для просмотра всем пользователям.

Структура API

API включает в себя следующие разделы:

Управление сегментами — позволяет получать, создавать и удалять сегменты. Для создания сегментов можно использовать: собственные данные, сегменты из Метрики, данные на основе геолокации, а также существующие сегменты (lookalike).
Управление разрешениями — позволяет получать информацию о текущих разрешениях, а также создавать и удалять разрешения на работу с сегментами.
Управление аккаунтами — позволяет получать список аккаунтов, представителем которых является пользователь.
Управление представителями — позволяет создавать, изменять и удалять представителей аккаунтов.
Управление пикселями — позволяет создавать, изменять и удалять пиксели.

Версионирование

Все разделы API Яндекс.Аудиторий поддерживают версионирование. У каждой версии есть определенный идентификатор (v1, v2 и т. п.). При выходе новой версии API предыдущая версия продолжает работать для поддержания обратной совместимости.

Если вы начинаете работу с API, используйте самую последнюю версию. Если вы уже используете предыдущие версии API, рекомендуем постепенно переходить на последнюю, т. к. поддержка старых версий ограничена во времени.

При формировании запроса к API всегда указывайте версию, с которой вы хотите работать.

https://api-audience.yandex.ru/v1/management/...
https://api-audience.yandex.ru/v2/management/...

Ресурсы

API Яндекс.Аудиторий построен по REST-принципам.

Все, чем можно управлять через API, представлено в виде ресурсов: сегмент, список сегментов, доступы к сегменту и т. д.

То есть ресурс — это некая целостная часть системы, с которой можно работать:

читать содержимое и текущее состояние ресурса (GET);
изменять содержимое и состояние и записывать его в ресурс (PUT);
удалять ресурс (DELETE);
выполнять специальные действия ― например, добавлять новые сегменты (POST).

У каждого ресурса есть свой уникальный URL. Все действия выполняются соответствующими методами протокола HTTP на URL'ы ресурсов.

Например, чтобы получить список сегментов, необходимо сделать GET-запрос на URL списка сегментов. А чтобы создать новый сегмент, необходимо сделать POST-запрос с телом сегмента на URL сегмента.