Для разработчиков REST MCP Agent Skill

API и интеграции

Встраивайте поиск мастеров, свободные слоты и онлайн-запись в свои сервисы — или подключите ИИ-ассистента через MCP.

Скачать OpenAPI-спецификацию Agent Skill

Аутентификация

Регистрация и вход возвращают пару JWT-токенов: token + refresh_token. Access-токен живёт 24 часа, refresh — 90 дней. Защищённые эндпоинты принимают заголовок Authorization: Bearer <token>.

ВходPOST /api/v1/auth/login

curl -X POST https://minibi.pro/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier": "user@example.com", "password": "Secret123"}'

Ответ200 · JSON

{
  "token": "<JWT access-токен — живёт 24 часа>",
  "refresh_token": "<refresh-токен — живёт 90 дней>",
  "expires_in": 86400,
  "user": {
    "id": "507f1f77bcf86cd799439111",
    "first_name": "Анна",
    "role": "master"
  }
}

Обновление парыPOST /api/v1/auth/refresh-token

curl -X POST https://minibi.pro/api/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<refresh_token из ответа login>"}'

Вход — по любому идентификатору: email, телефон E.164 или username.
Refresh-ротация: старый refresh после обмена перестаёт работать.
Лимит: 2 запроса/сек на auth-эндпоинты (429 при превышении).

Быстрый старт

Три запроса до первой записи

Все примеры — рабочий код против продакшен-API https://minibi.pro. Без регистрации и токенов.

Найти мастера

Поиск по запросу и гео-радиусу: запрос, координаты, радиус в километрах.

ЗапросGET /api/v1/masters/search

curl "https://minibi.pro/api/v1/masters/search?query=маникюр&lat=55.7558&lng=37.6173&radius_km=10&limit=5"

Ответ200 · JSON

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439111",
      "first_name": "Анна",
      "last_name": "Смирнова",
      "username": "anna.nails",
      "rating": 4.9,
      "reviews_count": 128,
      "address": "Москва, ул. Тверская, 10",
      "avatar_url": "https://firsts3.ru/beauty-photos/avatars/507f1f77bcf86cd799439111.jpg"
    }
  ]
}

В карточке: id, имя, username, rating, reviews_count, адрес, аватар. Дальше — GET /api/v1/masters/{id} за услугами.

Взять свободные слоты

Слоты на дату по набору услуг: длительность записи = сумма длительностей услуг.

ЗапросGET /api/v1/masters/{id}/slots

curl "https://minibi.pro/api/v1/masters/<master_id>/slots?service_ids=<service_id>&date=2026-11-01"

Ответ200 · JSON

[
  {
    "start": "10:00",
    "end": "11:00",
    "is_booked": false,
    "workspace_name": "Основное"
  },
  {
    "start": "11:00",
    "end": "12:00",
    "is_booked": true,
    "workspace_name": "Основное"
  }
]

Параметры: service_ids (CSV, обязательный), date YYYY-MM-DD, tz — смещение в минутах, workspace_id.

Записать клиента

Гостевой флоу без аккаунта: сначала код подтверждения на email, затем — запись.

Шаг 1 · кодPOST /api/v1/auth/send-code

curl -X POST https://minibi.pro/api/v1/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{"identifier": "client@example.com"}'

Шаг 2 · записьPOST /api/v1/guest/appointments

curl -X POST https://minibi.pro/api/v1/guest/appointments \
  -H "Content-Type: application/json" \
  -d '{
    "master_id": "507f1f77bcf86cd799439111",
    "service_ids": ["507f1f77bcf86cd799439222"],
    "start_time": "2026-11-01T10:00:00Z",
    "client_name": "Анна",
    "client_email": "client@example.com",
    "password": "Str0ngPass",
    "password_confirmation": "Str0ngPass",
    "code": "123456"
  }'

Ответ шага 1 — { "sent": true }. Rate limit: 2 запроса/сек на оба эндпоинта. Create-запрос создаёт аккаунт клиента (email + пароль) и подтверждённую запись.

REST API

Каталог, запись и задачи по REST

Каталог мастеров, услуги, слоты, отзывы, офферы, мероприятия, гостевая запись, а также задачи и проекты (по JWT) — JSON поверх HTTPS с курсорной пагинацией, ETag/304 на GET и машиночитаемыми ошибками {code, error}. Большинство GET-эндпоинтов публичны — токен нужен персонализированным сценариям и разделу задач и проектов.

Каталог мастеров

GET /masters/search

Поиск по тексту, гео-радиусу (lat/lng/radius_km), bounding box (sw/ne) и min_rating. Пагинация page/limit или курсор after.

GET /masters/autocomplete

Подсказки при вводе — имена, username, рабочие места. От 3 символов, до 20 результатов.

GET /masters/{id}

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

GET /masters/{id}/services

Активные услуги: длительность в минутах, price_from/price_to, валюта мастера.

GET /masters/{id}/schedule

Недельное расписание по дням недели, включая расписания рабочих мест.

GET /masters/{id}/available-days

Дни со свободными окнами в диапазоне from–to — для календаря записи. Плюс next-slots — ближайший слот по каждой услуге.

Отзывы, офферы, мероприятия

Отзывы · /api/v1

GET /masters/{id}/reviews — отзывы с фильтром по рейтингу и пагинацией limit/skip; …/reviews/distribution — количество оценок по звёздам 5…1 для рейтинговой гистограммы.

Офферы · /api/v2

GET /offers — лента опубликованных предложений с курсорной пагинацией и фильтрами hashtags/category; GET /offers/{id} — карточка со способами получения; GET /masters/{id}/offers — витрина мастера. Ответы кешируются (ETag).

Мероприятия · /api/v2

GET /events/{id} — карточка мероприятия (цена, расписание, места, участники); GET /masters/{id}/events — список (курсор). С Bearer-токеном карточка дополняется вашим статусом участия my_status.

Гостевая онлайн-запись

Главный сценарий интеграции: запись клиента к мастеру без аккаунта. Два запроса — код подтверждения на email (шаг 1 из быстрого старта), затем создание записи. Аккаунт клиента с паролем создаётся автоматически; существующему пользователю запись прикрепляется к его аккаунту после сверки кода. Если email уже занят чужим аккаунтом — 409 user_already_exists, гостевая запись никогда не уходит чужому аккаунту.

Поле	Обязательное	Описание
master_id	да	ID мастера (hex24)
service_ids	да	Массив ID услуг — длительность записи равна сумме услуг
start_time	да	Время начала, ISO 8601 UTC
client_name	да	Имя клиента
code	да	Код подтверждения из шага 1 (живёт 15 минут)
password, password_confirmation	да	Пароль создаваемого аккаунта: 8+ символов, заглавная + строчная буква + цифра
client_email или client_phone	один из	Контакт гостя: email (основной путь) или телефон E.164 (легаси)
workspace_id	нет	Рабочее место, если у мастера их несколько
note, source, utm_*	нет	Комментарий мастеру, маркировка источника, UTM-метки
terms_acceptance, personal_data_consent	нет*	Юридические согласия; версии — из GET /api/v1/legal/manifest

* Рекомендуем передавать согласия всегда: версии документов берутся из GET /api/v1/legal/manifest.

Правила и ограничения

Формат ошибок

Любая ошибка — JSON с машинным кодом и текстом:

ОшибкаHTTP ≠ 2xx

{ "code": "time_slot_not_available", "error": "Выбранное время уже занято" }

HTTP	code	Когда
400	code_invalid	Неверный или истекший код подтверждения
400	legal_consent_required	Не переданы обязательные юридические согласия
401	invalid_credentials	Неверный идентификатор или пароль
404	—	Ресурс не найден или скрыт настройками приватности
409	email_taken	Email уже зарегистрирован
409	user_already_exists	Email гостя занят существующим аккаунтом
409	time_slot_not_available	Выбранное время только что заняли
429	too_many_attempts	Превышен rate limit (2 запроса/сек, burst 5)

Rate limits

Auth- и гостевые мутации — 2 запроса/сек, burst 5, дальше 429. Коды отправки — кулдаун 60 сек и 3 кода за 5 минут на идентификатор.

CORS

Серверные интеграции работают без ограничений. Для браузерных добавим ваш origin по запросу — напишите на minibils2026@gmail.com.

Кеширование

GET-ответы отдают ETag / Last-Modified и поддерживают условные запросы — If-None-Match возвращает 304 без тела.

Пагинация

Списки — курсорная пагинация: cursor.after + has_more; точечные лимиты — параметром limit.

Все эндпоинты

Все 52 эндпоинта платформы: публичный каталог и гостевая запись + задачи и проекты по JWT-токену. Полные схемы запросов и ответов — в openapi.yaml.

Метод	Путь	Назначение
Мастера — /api/v1
GET	/api/v1/masters/search	Поиск мастеров: текст, гео-радиус или bbox, min_rating, пагинация
GET	/api/v1/masters/autocomplete	Подсказки поиска от 3 символов
GET	/api/v1/masters/{master_id}	Карточка мастера: профиль, услуги, рабочие места
GET	/api/v1/masters/{master_id}/services	Активные услуги мастера
GET	/api/v1/masters/{master_id}/schedule	Недельное рабочее расписание
GET	/api/v1/masters/{master_id}/slots	Свободные слоты на дату по набору услуг
GET	/api/v1/masters/{master_id}/next-slots	Ближайший свободный слот по каждой услуге
GET	/api/v1/masters/{master_id}/available-days	Дни со свободными окнами в диапазоне дат
GET	/api/v1/masters/{master_id}/reviews	Отзывы о мастере (limit, skip, rating)
GET	/api/v1/masters/{master_id}/reviews/distribution	Распределение оценок 5…1
Лендинги и веб-запись — /api/public
GET	/api/public/masters	Постраничный список публичных мастеров
GET	/api/public/masters/popular	Популярные мастера (до 8)
GET	/api/public/masters/{id}	Публичная карточка мастера (context=booking)
GET	/api/public/masters/{id}/workspaces	Рабочие места для страницы записи
GET	/api/public/masters/{id}/posts	Посты-референсы мастера (курсор)
GET	/api/public/masters/{id}/reviews	Последние отзывы (до 10)
Офферы и мероприятия — /api/v2
GET	/api/v2/offers	Лента опубликованных офферов (cursor, hashtags)
GET	/api/v2/offers/{id}	Карточка оффера со способами получения
GET	/api/v2/masters/{master_id}/offers	Офферы мастера
GET	/api/v2/events/{id}	Карточка мероприятия (с токеном — my_status)
GET	/api/v2/masters/{master_id}/events	Активные мероприятия мастера
Гостевая запись
POST	/api/v1/guest/appointments	Гостевая онлайн-запись к мастеру (два шага)
POST	/api/v2/events/{id}/join-guest	Гостевое участие в мероприятии
Аутентификация
POST	/api/v1/auth/register	Регистрация (email + пароль + согласия)
POST	/api/v1/auth/login	Вход по identifier и паролю
POST	/api/v1/auth/refresh-token	Обмен refresh-токена на новую пару
POST	/api/v1/auth/send-code	Код подтверждения на email
Задачи и проекты — /api/v2 (JWT; создание проекта — тариф Pro)
GET/POST	/api/v2/projects	Проекты: список моих (владелец/участник) / создать (Pro)
GET/PATCH/DELETE	/api/v2/projects/{id}	Проект: карточка / обновить / удалить
PUT	/api/v2/projects/{id}/statuses	Перезаписать набор статусов-колонок проекта
POST	/api/v2/projects/{id}/members	Добавить участника проекта
DELETE	/api/v2/projects/{id}/members/{user_id}	Удалить участника проекта
POST	/api/v2/projects/{id}/invites	Пригласить по email / телефону / username
GET	/api/v2/projects/{id}/report	Отчёт по задачам (from/to, план-факт)
POST	/api/v2/project_invites/{invite_id}/accept	Принять приглашение в проект
POST	/api/v2/project_invites/{invite_id}/decline	Отклонить приглашение в проект
GET	/api/v2/my/project_invites	Мои активные приглашения
GET/POST	/api/v2/tasks	Задачи: список (project_id, фильтры) / создать
GET	/api/v2/my/tasks	Мои открытые задачи
GET/PATCH/DELETE	/api/v2/tasks/{id}	Задача: карточка / обновить / удалить
GET	/api/v2/tasks/{id}/history	История изменений статусов задачи
POST	/api/v2/tasks/{id}/attachments	Прикрепить файл к задаче
DELETE	/api/v2/tasks/{id}/attachments/{attachment_id}	Удалить вложение задачи
GET/POST	/api/v2/tasks/{id}/links	Связи задачи: список / связать (relates/blocks)
DELETE	/api/v2/tasks/{id}/links/{linked_task_id}	Удалить связь задач
GET/POST	/api/v2/tasks/{id}/comments	Комментарии задачи: список / добавить
PUT/DELETE	/api/v2/tasks/task_comments/{id}	Комментарий: редактировать / удалить
GET	/api/v2/tasks/task_comments/{id}/replies	Ответы на комментарий
POST	/api/v2/tasks/media	Загрузка фото для вложения (multipart, до 50 МБ)
Служебные
GET	/api/v1/subscriptions/plans	Тарифные планы подписки
GET	/api/v1/legal/manifest	Версии юридических документов
GET	/api/v1/app/version	Минимальные и актуальные версии приложений

MCP для ИИ-ассистентов

Вся платформа как инструмент ИИ-агента

MCP-сервер платформы: базовый набор из 35 инструментов — поиск мастеров, записи, задачи, чаты, офферы и мероприятия, личные события и управление онлайн-записью. Полный набор (294 инструмента) — по запросу. Агент работает с теми же правами и лимитами, что и приложение.

Токен

Подключение за минуту

1 Создайте токен: откройте личный кабинет minibi.pro/cabinet → Настройки → Токены интеграции → Создать. Токен показывается один раз — скопируйте его.
2 Добавьте сервер в MCP-клиент (Cursor, ZCode, Claude и др.):

Конфиг MCP-клиентаmcp.json

{
  "mcpServers": {
    "minibi": {
      "url": "https://minibi.pro/mcp",
      "headers": { "Authorization": "Bearer <ваш токен>" }
    }
  }
}

3 Готово: инструменты работают от вашего имени с теми же правами, что и приложение.

Токен начинается с mbk_… — можно держать до 5 активных. Удаление токена в кабинете мгновенно отзывает доступ.

Пример сессии

Работа с календарём записей сразу после подключения:

MCP-сессияtools/list → appointments_list

# 1. Сразу после подключения клиент получает список инструментов
tools/list
→ { "tools": [ … ] }   # базовый набор — 35 инструментов

# 2. Токен уже идентифицирует вас — auth_login не нужен:
#    любой инструмент сразу работает от вашего имени
appointments_list(date: "2026-11-01", tz: 180)
→ {
  "appointments": [
    {
      "start_time": "10:00",
      "end_time": "11:30",
      "client_name": "Мария Иванова",
      "service_name": "Маникюр с покрытием",
      "status": "confirmed"
    }
  ]
}

Dev-стек: http://localhost:8085/mcp.

Готовые артефакты

Скачайте и работайте

OpenAPI 3.0 — openapi.yaml

Спецификация API в OpenAPI 3.0 — каталог, онлайн-запись, задачи и проекты: параметры, схемы ответов, коды ошибок. Импортируется в Postman, Insomnia и GPT Actions без доработок.

Agent Skill — minibi-api

Готовый навык для ИИ-агентов: поиск мастеров и гостевая запись.

Скачайте zip-архив
Подключите к своему ИИ-агенту (в Claude: Settings → Capabilities → Skills)
Загрузите архив

FAQ

Частые вопросы

Нужен ли токен для поиска мастеров?

Нет. Все GET-эндпоинты каталога, отзывов, офферов и мероприятий публичны и работают без авторизации. Bearer-токен лишь персонализирует выдачу: поиск учитывает интересы пользователя, а у мероприятий появляется поле my_status.

Какие лимиты у API?

Аутентификация и гостевые мутации (send-code, guest/appointments, join-guest) — 2 запроса/сек с burst 5, при превышении 429. Публичные GET не лимитированы так агрессивно, но мы рекомендуем кешировать ответы (ETag / Cache-Control уже отдаются).

Как получить Bearer-токен для MCP?

Создайте его сами в личном кабинете (minibi.pro/cabinet): Настройки → Токены интеграции → Создать. Токен формата mbk_… показывается один раз — скопируйте его. Лимит — 5 активных токенов; удаление токена отзывает доступ.

Как ведётся версионирование?

Версия указана в пути: /api/v1 и /api/v2. Изменения обратной совместимости (новые поля, новые эндпоинты) происходят без увеличения версии; ломающие изменения — только в новой версии с анонсом заранее.

Куда писать, если что-то не работает?

minibils2026@gmail.com — разберём запрос, подскажем по эндпоинтам и добавим origin в CORS для браузерных интеграций.