Поселково

API Поселково

Всё, что человек делает в интерфейсе, он может сделать программой или голосом через своего ассистента. Это не два продукта с разными возможностями: и страница, и HTTP-запрос, и вызов инструмента MCP приводят к одному коду.

Практическое следствие: если что-то есть в интерфейсе, оно есть и в API, и наоборот. Расхождение — это баг, а не «ещё не сделали».

С чего начать

  1. Получите токен. Личный, в настройках, — если программа ваша и работает от вашего имени. Через OAuth — если вы делаете приложение для других людей.
  2. Посмотрите, какие скоупы вам нужны. По умолчанию выдаётся только чтение, и для начала это правильный выбор.
  3. Найдите свой поселок: GET /api/v1/settlements. Единственный эндпоинт, которому не нужен токен, и почти всё остальное просит slug отсюда.
  4. Прочитайте про пагинацию и ошибки — там три вещи, которые иначе придётся выяснять по ответам сервера.

Если вы подключаете ассистента, а не пишете код, вам нужна одна страница: как подключить своего ассистента.

Две двери

HTTP API, /api/v1/… — для программы, скрипта, интеграции. MCP, /mcp/{аудитория} — для ассистента, которого вы подключаете сами.

За обеими один и тот же OAuth, одни и те же токены и одни и те же права. Токен, отозванный в настройках, перестаёт работать сразу в обеих.

Справочник и спецификация

Справочник эндпоинтов — все адреса с параметрами, разрешениями и примерами. /developers/openapi.json — то же самое машиночитаемо, OpenAPI 3.1: его понимают Postman, Insomnia и генераторы клиентов.

И то и другое собирается из кода при каждом деплое, а не пишется руками, поэтому не расходится с тем, что сервер действительно принимает.

Что важно знать сразу

Версия v1 нестабильна. Пока у API нет ни одного внешнего потребителя, который не может обновиться синхронно с нами, ломающие изменения выходят в v1. Подробно — в разделе про версии.

Перечисления передаются именами, а не числами. "claimed_role": "co_owner", а не 2. Внутри они хранятся числами ради размера индексов, но наружу число непригодно: его нельзя прочитать в контракте и по нему невозможно догадаться, что оно значит.

Идентификаторы — строки. Это снежинки, они не помещаются в число JavaScript без потери точности, поэтому приходят и принимаются как строки.