> For the complete documentation index, see [llms.txt](https://palert.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://palert.gitbook.io/docs/enterprise/api.md).

# Palert API

Palert API для тарифа Enterprise — личные ключи, базовый адрес, первый запрос, методы, страницы, ошибки, лимиты и журнал запросов.

**Palert API** — REST API к вашим данным в Palert: отслеживаниям и их ценам, истории, отчётам по всему ассортименту за период, уведомлениям, покупкам и выгоде, ленте скидок, проверке цены и идеям. Через него данные Palert можно забирать в Google Таблицы, n8n, свои скрипты, боты и дашборды, а также добавлять и менять отслеживания из своего кода. API работает с тем же аккаунтом, тарифом и квотами, что и кабинет, и отдаёт только данные вашего аккаунта и рабочего пространства — выгрузки всей базы цен в нём нет.

{% hint style="info" %}
**Доступ по личному ключу — только на тарифе Enterprise.** Если нужно просто спрашивать о своих товарах в Claude, ChatGPT или Cursor, ключ не нужен: подключите [ИИ-ассистента](https://palert.gitbook.io/docs/rukovodstvo-polzovatelya/ai-assistants.md) — с тарифа Pro для вопросов и с Premium для изменений.
{% endhint %}

## Раздел «API» в кабинете

На тарифе Enterprise в боковом меню кабинета [app.palert.ru](https://app.palert.ru/) есть пункт **«API»** (на телефоне меню открывается кнопкой «Разделы» в нижней панели, на планшете — кнопкой ☰). В нём четыре вкладки:

* **«Обзор»** — запросы и ошибки за сегодня, лимит скорости, число активных ключей, график запросов за 14 дней, последние запросы и **«Быстрый старт»**;
* **«Ключи API»** — создание и отзыв ключей;
* **«Журнал»** — все запросы к API за последние 30 дней;
* **«Документация»** — описание всех методов с примерами на cURL, Python и JavaScript.

Документация открывается на любом тарифе по прямой ссылке [app.palert.ru/developers/docs](https://app.palert.ru/developers/docs) — её можно изучить до подключения Enterprise.

## Как создать ключ

1. Откройте **«API»** → **«Ключи API»** и нажмите **«Создать ключ»**.
2. Укажите **название** (до 60 символов) — чтобы потом было понятно, где используется ключ, например «n8n» или «Google Таблицы».
3. Выберите **права**:
   * **«Только чтение»** — списки, история цен, скидки, покупки, идеи, проверка цены и отзыв; ваши данные ключ не меняет;
   * **«Чтение и запись»** — а ещё добавление, изменение и удаление отслеживаний и покупок, группы, идеи и голоса за них.
4. Выберите **срок действия**: 30 дней, 90 дней, 1 год или без срока. Ключ со сроком безопаснее — забытый ключ сам перестанет работать.
5. Нажмите **«Создать ключ»** и сразу скопируйте его.

{% hint style="warning" %}
**Ключ — как пароль.** Palert показывает его один раз, сразу после создания, и хранит только отпечаток. Сохраните ключ в менеджере паролей или в переменной окружения (в примерах — `PALERT_API_KEY`). Не публикуйте ключ и не вставляйте его в код сайта или расширения. Потеряли ключ — отзовите его и создайте новый.
{% endhint %}

* Активных ключей может быть до 10.
* Выдавайте ключу только те права, которые нужны интеграции. У наблюдателя в [рабочем пространстве](https://palert.gitbook.io/docs/enterprise/workspace.md) ключ выпускается только на чтение.
* **Отозвать** ключ можно в той же таблице: кнопка **«Отозвать»** → **«Да, отозвать»**. Запросы с ним сразу начнут получать ошибку, отменить это нельзя.
* В таблице видно, когда ключ создан, когда и с какого IP-адреса использовался последний раз и до какого числа действует.
* Если тариф сменился на более низкий, ключи перестают работать — запросы получают ошибку `plan_required`. Сами ключи сохраняются и снова заработают после возвращения на Enterprise.

## Адрес и авторизация

Базовый адрес: `https://api.palert.ru/v1`

Передавайте ключ в заголовке `Authorization` в каждом запросе:

```
Authorization: Bearer palert_pat_xxxxxxxxxxxxxxxx
```

Ключ в адресе запроса или в cookie API не примет. Вызывайте API с сервера, из n8n или скриптов: из браузера запросы не пройдут, а ключ в коде страницы увидел бы любой посетитель.

Ассистент, подключённый через раздел «ИИ-ассистенты», получает свой ключ (он начинается с `palert_oat_`). Такой ключ работает только в MCP, в API он не подойдёт — для API нужен личный ключ `palert_pat_`.

## Первый запрос

Метод `/me` вернёт ваш тариф, лимиты и сколько запросов вы уже сделали сегодня:

```bash
export PALERT_API_KEY="palert_pat_…"

curl "https://api.palert.ru/v1/me" \
  -H "Authorization: Bearer $PALERT_API_KEY"
```

Список отслеживаний в коротком виде:

```bash
curl "https://api.palert.ru/v1/trackings?view=compact&limit=50" \
  -H "Authorization: Bearer $PALERT_API_KEY"
```

Поставить товар на отслеживание с ожидаемой ценой (нужен ключ с правом записи):

```bash
curl -X POST "https://api.palert.ru/v1/trackings" \
  -H "Authorization: Bearer $PALERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.ozon.ru/product/naushniki-sony-wh-1000xm5-1728110604/", "target_price": 22000}'
```

Цены нового отслеживания появятся после первого обхода, обычно через 1–5 минут.

## Формат данных

* Запросы и ответы — JSON в кодировке UTF-8. Методы — GET, POST, PATCH и DELETE; тело запроса — JSON-объект до 64 КБ.
* Цены — числа в валюте аккаунта, рядом всегда поле `currency`. Цены отслеживаний учитывают вашу скидку покупателя и пошлину, как в кабинете; цены ленты скидок — акции самих площадок, без скидки покупателя.
* Даты — ISO 8601 с часовым поясом Москвы (`2026-10-12T14:03:00+03:00`), дни — `YYYY-MM-DD`.
* Если значения нет — `null`, а не пустая строка.
* Версия указана в пути (`/v1`). Новые поля в ответах появляются без смены версии, поэтому код должен пропускать поля, которых он не знает. Убрать или переименовать поле можно только в новой версии (`/v2`) — старая продолжит работать.
* В каждом ответе есть заголовок `X-Request-Id` — укажите его, когда пишете в поддержку.

## Методы

Полное описание параметров и ответов — во вкладке **«Документация»**. Права: **чтение** — все GET-запросы, проверка цены, проверка фильтров и отзыв; **запись** — всё остальное.

### Аккаунт и площадки

| Метод            | Что делает                                                                                                                                            | Права  |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `GET /me`        | Аккаунт, тариф, лимиты тарифа и их использование, ключ запроса и квота API на сегодня. Удобно вызывать первым                                         | чтение |
| `GET /platforms` | Площадки Palert. Поле `id` передаётся как `platform_id` в других запросах, `name_search` показывает, работает ли на площадке отслеживание по названию | чтение |

### Отслеживания

| Метод                                         | Что делает                                                                                                                                                                                                                                                                     | Права  |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| `GET /trackings`                              | Список отслеживаний с лучшей ценой и настройками уведомлений. Фильтры по статусу, группе, площадке и названию, сортировка; `view=compact` — короткие строки                                                                                                                    | чтение |
| `POST /trackings`                             | Поставить на отслеживание товар по ссылке или артикулу (`url`) или по названию (`query` и `platform_ids`, можно сразу с `filters`). Каждая площадка из `platform_ids` занимает одну ссылку в лимите отслеживания — он общий для всех площадок, как в кабинете                  | запись |
| `GET /trackings/{id}`                         | Отслеживание с предложениями, минимумом и средней ценой за 30 дней                                                                                                                                                                                                             | чтение |
| `PATCH /trackings/{id}`                       | Изменить только переданные поля: статус (пауза, архив), группу, уведомления, а у отслеживания по названию — фильтры, название и площадки                                                                                                                                       | запись |
| `DELETE /trackings/{id}`                      | Удалить отслеживание вместе с историей цен, без восстановления. Убрать на время — `PATCH` со `status: archived`                                                                                                                                                                | запись |
| `GET /trackings/{id}/history`                 | Лучшая цена по дням. Глубина — по тарифу                                                                                                                                                                                                                                       | чтение |
| `GET /trackings/{id}/items/{item_id}/history` | Цены одного товара, как график товара в кабинете: по дням (закрытие, минимум, максимум, остаток) или `detail=all` — «Все данные», как в кабинете: за свежий период каждая записанная цена, за более ранний — фактические изменения (Premium и Enterprise). Глубина — по тарифу | чтение |
| `GET /trackings/{id}/items`                   | Найденные предложения с вердиктом фильтров: что проходит, что отсеяно и почему                                                                                                                                                                                                 | чтение |
| `POST /trackings/{id}/filter-preview`         | Показать, что сделают новые фильтры, ничего не сохраняя. Только для отслеживаний по названию                                                                                                                                                                                   | чтение |

### Группы

| Метод                 | Что делает                                                                                                                     | Права  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------ |
| `GET /groups`         | Группы с числом активных и архивных отслеживаний                                                                               | чтение |
| `GET /groups/{id}`    | Одна группа                                                                                                                    | чтение |
| `POST /groups`        | Создать группу                                                                                                                 | запись |
| `PATCH /groups/{id}`  | Изменить название и описание группы                                                                                            | запись |
| `DELETE /groups/{id}` | Удалить группу. По умолчанию её отслеживания остаются без группы, с `with_trackings=true` удаляются и ваши отслеживания группы | запись |

### Цены, скидки и уведомления

| Метод                          | Что делает                                                                                                                                                                          | Права  |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `GET /price-drops`             | Что подешевело среди активных отслеживаний за выбранное число дней                                                                                                                  | чтение |
| `POST /price-checks`           | Проверить цену товара по ссылке или артикулу: вердикт по истории, минимум, медиана, рекомендуемый порог. Квота проверок общая с сайтом, мини-приложениями и ботами в Telegram и MAX | чтение |
| `GET /price-checks/{check_id}` | Результат проверки, если товар новый и цена ещё загружалась (`status: queued`)                                                                                                      | чтение |
| `GET /discounts`               | Лента проверенных скидок, как раздел «Скидки»                                                                                                                                       | чтение |
| `GET /notifications`           | Ваши уведомления, новые первыми. API их только читает и не отмечает прочитанными                                                                                                    | чтение |

### Отчёты по ассортименту

Отчёт за один запрос охватывает все активные отслеживания — до 1000 самых новых (если их больше, в ответе будет `truncated: true`; сузьте отчёт параметрами `group_id` или `platform_id`). Период — `days`, от 1 до 90 дней, глубину ограничивает тариф, как у истории цены. В начале ответа — `summary`: итоги по всем отслеживаниям отчёта, а не только по странице. Строки по умолчанию короткие (`view=compact`), с `view=full` — с группой, площадками и ссылкой на отслеживание в кабинете.

| Метод                   | Что делает                                                                                                                                                                                                                                                                                                                   | Права  |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `GET /reports/prices`   | Как менялись цены: по каждому отслеживанию цена в начале и в конце периода, изменение в процентах, типичная цена (медиана), низкая и высокая цена, сколько раз цена менялась, дни без наличия. Фильтры — подешевевшие или подорожавшие и изменение от N %, сортировка — по силе изменения, числу изменений, ширине диапазона | чтение |
| `GET /reports/corridor` | Выход за коридор цены — для отслеживаний с уведомлением «Коридор цены» (например, РРЦ): сколько дней и насколько цена была ниже нижней или выше верхней границы, когда это было, что сейчас и какие продавцы давали самую низкую цену в эти дни                                                                              | чтение |
| `GET /reports/stock`    | Наличие: что было распродано и сколько дней, что распродано сейчас и с какого дня, что вернулось в продажу                                                                                                                                                                                                                   | чтение |

Цены в отчётах — лучшая цена отслеживания по дням, такая же, как на графике и в `GET /trackings/{id}/history`. Однодневные резкие скачки цены (часто это сбой на площадке) не считаются изменением цены и нарушением коридора, а изменение, похожее на сбой, помечено `suspicious: true` — его стоит проверить по графику.

```bash
curl "https://api.palert.ru/v1/reports/prices?days=30&direction=down&min_percent=10" \
  -H "Authorization: Bearer $PALERT_API_KEY"
```

### Покупки и выгода

| Метод                    | Что делает                                                    | Права  |
| ------------------------ | ------------------------------------------------------------- | ------ |
| `GET /purchases`         | Ваши покупки (отметки «Куплено») с выгодой и итогами          | чтение |
| `POST /purchases`        | Отметить покупку по своему отслеживанию, как кнопка «Куплено» | запись |
| `PATCH /purchases/{id}`  | Изменить покупку                                              | запись |
| `DELETE /purchases/{id}` | Удалить отметку о покупке; отслеживание остаётся              | запись |
| `GET /savings/potential` | Возможная выгода — как одноимённый виджет кабинета            | чтение |

### Идеи и отзыв

| Метод                     | Что делает                                                                                  | Права  |
| ------------------------- | ------------------------------------------------------------------------------------------- | ------ |
| `GET /ideas`              | Идеи пользователей Palert, с поиском. Авторов API не показывает                             | чтение |
| `GET /ideas/categories`   | Категории идей                                                                              | чтение |
| `GET /ideas/{id}`         | Идея и последние 50 комментариев                                                            | чтение |
| `POST /ideas`             | Предложить идею                                                                             | запись |
| `POST /ideas/{id}/vote`   | Проголосовать за идею                                                                       | запись |
| `DELETE /ideas/{id}/vote` | Снять голос                                                                                 | запись |
| `POST /feedback`          | Отзыв об API и коннекторе для команды Palert. Это не обращение в поддержку: ответа не будет | чтение |

## Страницы списков

Списки возвращают объект `list`:

```json
{
  "object": "list",
  "data": [{ "object": "tracking", "id": 123, "title": "Наушники Sony WH-1000XM5" }],
  "has_more": true,
  "next_cursor": "MTIz"
}
```

Чтобы получить следующую страницу, передайте `next_cursor` как есть в параметре `cursor` — с теми же параметрами сортировки и фильтров, что в первом запросе:

```bash
curl "https://api.palert.ru/v1/trackings?limit=50&cursor=MTIz" \
  -H "Authorization: Bearer $PALERT_API_KEY"
```

* Размер страницы — параметр `limit`, обычно от 1 до 100. Значение по умолчанию у методов разное, оно указано в документации метода.
* Лента скидок (`GET /discounts`) — исключение: обычные страницы через `page` и `per_page`.
* «Что подешевело» и «Возможная выгода» приходят одним ответом размером `limit`, без следующих страниц (`has_more` всегда `false`).
* Отчёты по ассортименту листаются через `next_cursor`, а `summary` и `total` в каждом ответе — по всему отчёту.

## Ошибки

При ошибке API отвечает статусом 4xx или 5xx и объектом `error`:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Параметр «days» — от 1 до 1095.",
    "param": "days"
  },
  "request_id": "req_6f1c2a9b0d3e4f5a6b7c8d9e"
}
```

Ветвите логику по полю `code` — оно стабильно, а текст `message` написан по-русски и может меняться. Если пришёл код, которого нет в документации, ориентируйтесь на `type` и HTTP-статус.

| HTTP               | `type`                  | Что случилось                                                                     | Частые `code`                                                                                                 |
| ------------------ | ----------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| 400, 405, 413, 415 | `invalid_request_error` | Неверные параметры, тело или метод запроса                                        | `invalid_json`, `invalid_parameter`, `missing_parameter`, `method_not_allowed`, `payload_too_large`           |
| 401                | `authentication_error`  | Ключа нет, он неверный, истёк или отозван                                         | `missing_api_key`, `invalid_api_key`, `expired_api_key`, `revoked_api_key`                                    |
| 403                | `permission_error`      | Ключу не хватает прав, у вас доступ только на чтение или учётная запись неактивна | `insufficient_scope`, `workspace_read_only`, `account_inactive`                                               |
| 403                | `plan_limit_error`      | Нужен другой тариф или исчерпан лимит тарифа                                      | `plan_required`, `tracking_limit_reached`, `link_limit_reached`, `group_limit_reached`, `tracking_restricted` |
| 404                | `not_found_error`       | Объект не найден или принадлежит другому пользователю; нет такого метода          | `not_found`, `tracking_not_found`, `route_not_found`                                                          |
| 409                | `conflict_error`        | Конфликт: например, товар уже отслеживается                                       | `already_tracking`, `busy`                                                                                    |
| 422                | `invalid_request_error` | Покупку нельзя отметить: у отслеживания ещё нет начальной цены                    | `initial_price_unavailable`                                                                                   |
| 429                | `rate_limit_error`      | Слишком много запросов — подождите `Retry-After` секунд                           | `rate_limit_exceeded`, `daily_limit_exceeded`, `too_many_concurrent_requests`, `price_check_quota_exceeded`   |
| 500                | `api_error`             | Сбой на нашей стороне — повторите запрос позже                                    | `internal_error`                                                                                              |

## Лимиты

Лимиты считаются на пользователя, а не на ключ: все ваши ключи и подключённые ИИ-ассистенты делят одну квоту — в минуту и в сутки. Минутный счётчик отсчитывается с первого запроса, суточный обнуляется в полночь по Москве. На Enterprise лимиты можно поднять по договору.

Где посмотреть свои цифры:

* в кабинете — **«API»** → **«Обзор»** (лимит скорости и запросы за сегодня) и **«Документация»** → **«Лимиты»** (таблица по тарифам);
* в ответе `GET /me` — поле `api.rate_limit`;
* в заголовках каждого ответа на запрос с ключом:

```
X-RateLimit-Limit: <в минуту>
X-RateLimit-Remaining: <осталось в этой минуте>
X-RateLimit-Reset: <секунд до обнуления минутного счётчика>
X-RateLimit-Limit-Day: <в сутки>
X-RateLimit-Remaining-Day: <осталось на сегодня>
```

Если лимит превышен, API ответит статусом 429 с заголовком `Retry-After` — подождите указанное число секунд и повторите запрос. Одновременных запросов тоже не может быть много: получили `too_many_concurrent_requests` — дождитесь ответа на предыдущие.

Квоты тарифа — число отслеживаний, глубина истории, проверки цены — те же, что в кабинете.

## Документация и спецификация OpenAPI

* **Интерактивная документация** — **«API»** → **«Документация»** ([app.palert.ru/developers/docs](https://app.palert.ru/developers/docs)): поиск по методам, параметры, примеры запросов и ответов, возможные ошибки. Туда же ведёт адрес [api.palert.ru](https://api.palert.ru).
* **Спецификация OpenAPI 3.1** — `https://api.palert.ru/v1/openapi.json`, по-русски; по-английски — с параметром `?lang=en`. Подходит для Postman, Insomnia, генераторов клиентов и ИИ-ассистентов. Скачать её можно и кнопкой **«Скачать openapi.json»** в документации.
* `GET https://api.palert.ru/v1/` — краткие сведения об API.

Спецификация и сведения об API открываются без ключа.

## Журнал запросов

Вкладка **«API»** → **«Журнал»** показывает все запросы к API за последние 30 дней: время, метод и адрес, статус, длительность, ключ и IP-адрес. Запросы можно отфильтровать по статусу (успешные или с ошибками) и по ключу. Если пишете в поддержку, скопируйте ID запроса из журнала — так мы быстрее найдём, что пошло не так.

## Личный ключ в MCP-клиенте

Личный ключ Enterprise принимает и MCP-сервер Palert `https://mcp.palert.ru` — для клиентов, которые не умеют входить через OAuth, а позволяют только указать заголовок `Authorization: Bearer <ключ>`. Права — как у ключа: только чтение или чтение и запись. Через MCP действуют те же ограничения, что для ИИ-ассистентов: нельзя удалить группу, а имя и e-mail в ответах не передаются. Обычное подключение ассистентов со входом через Palert описано в разделе [ИИ-ассистенты](https://palert.gitbook.io/docs/rukovodstvo-polzovatelya/ai-assistants.md).

## Вебхуки и выгрузки

Вебхуки, выгрузки и повышенные лимиты подключаются на Enterprise по договору. Чтобы обсудить условия, [напишите в поддержку](https://palert.gitbook.io/docs/chastye-voprosy-i-podderzhka/contact-support.md).
