Read API Маркета

Версия API 1.0.0 · тариф Fleet · только чтение

Читайте свои данные Маркета из скрипта на своём сервере: поиск и списки каталога, карточки расширений, наблюдаемые, сохранённые поиски, радар портфеля и выгрузку в CSV. API отвечает на те же вопросы, что экраны Маркета, с теми же лимитами, от имени аккаунта, которому принадлежит ключ.

↓ Скачать OpenAPI 3.1 (YAML) /market-read-api-openapi.yaml · info.version 1.0.0

1. Создайте ключ

В веб-приложении откройте Настройки, затем Аккаунт, затем API-ключи и создайте ключ. Полный ключ показывается один раз, сразу после создания: сохраните его в хранилище секретов. Мы храним только его SHA-256-хэш, поэтому потерянный ключ не восстановить, только заменить.

Ключ выглядит так:

eop_k3j5x7q2m4n6p_7t2w4y6a3c5e7g2j4l6n3q5s7u2w4y6a3c5e7g2j4l6n3q5s7u2w4y6a

Часть до второго подчёркивания – публичный префикс ключа. Настройки показывают его рядом с названием, датой создания и последнего использования, чтобы ключи можно было различить без секрета.

2. Вызовите API

Передайте ключ как bearer-токен. Все маршруты – GET под одним префиксом:

curl -s https://extops.dev/api/v1/market/read/watchlist \
  -H "Authorization: Bearer $EXTOPS_API_KEY"

Маршрут	Что возвращает
`/search`	Поиск по каталогу с параметрами Explorer: текст, режим, фильтры, сортировка, страницы.
`/lists/{kind}`	Один из массовых списков: новые, снятые, релизы, движение и остальные.
`/categories`	Категории магазина с размерами.
`/extensions/{id}`	Карточка расширения с историей и активностью в магазине.
`/extensions/{id}/timeline`	Следующие страницы ленты активности карточки в магазине.
`/watchlist`	Расширения, за которыми вы наблюдаете.
`/segments`	Ваши сохранённые поиски.
`/segments/{id}/members`	Расширения одного сохранённого поиска на последний закрытый проход каталога.
`/portfolio/radar`	Всё, что изменилось в ваших сохранённых поисках, наблюдаемых и своих расширениях, каждое расширение один раз.
`/export`	Поиск или список в CSV, до 5 000 строк.

Ответы – тот же JSON, что читает веб-приложение; поля описаны в файле OpenAPI. API только читает: маршрутов записи нет, любой метод кроме GET отклоняется.

3. Чьи данные видит ключ

Ключ принадлежит вашему аккаунту и действует от его имени. Сохранённые поиски, наблюдаемые и радар – только ваши: сохранённый поиск другого аккаунта отвечает 404, так же как несуществующий. Списки каталога режутся вашим тарифом так же, как на экране.

4. Лимиты

120 запросов в минуту на аккаунт, суммарно по всем его ключам: второй ключ не даёт второй квоты. Каждый ответ несёт X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset.
Ваши вызовы учитываются в том же дневном бюджете Маркета, что и в приложении: ключ – это вы, а не вторая квота.
Экспорт CSV: до 5 000 строк в файле и 50 файлов в сутки на аккаунт.
До 5 активных ключей на аккаунт – достаточно для замены без простоя.

При превышении лимита API отвечает 429 с Retry-After и временем сброса в details.reset_at.

5. Замена, отзыв и смена тарифа

Замена выпускает новый ключ и сразу останавливает старый. Чтобы заменить ключ без простоя, создайте второй ключ, выкатите его, затем отзовите первый. Отозвать ключ можно на любом тарифе.

API входит в тариф Fleet. Если тариф сменился, ключи не удаляются: вызовы отвечают 403 с plan_required, настройки показывают ключи приостановленными, а после возврата на Fleet те же ключи снова работают.

6. Ошибки

Статус	Код	Значение
401	`api_key_invalid`	Ключа нет, он неизвестен или повреждён.
401	`api_key_revoked`	Ключ отозван или заменён.
403	`api_key_scope`	Область действия ключа не покрывает этот маршрут.
403	`plan_required`	Сейчас ваш тариф не включает API.
429	`rate_limited`	Лимит исчерпан до времени в `details.reset_at`.