For developers REST MCP Agent Skill

API & Integrations

Embed master search, available slots and online booking into your services — or connect an AI assistant via MCP.

Download OpenAPI specification Agent Skill

Authentication

Registration and login return a pair of JWT tokens: token + refresh_token. The access token lives for 24 hours; the refresh token lasts 90 days. Protected endpoints accept the Authorization: Bearer <token> header.

LoginPOST /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"}'

Response200 · JSON

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

Refresh pairPOST /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>"}'

Login works with any identifier: email, E.164 phone or username.
Refresh rotation: the old refresh token stops working after exchange.
Limit: 2 requests/sec on auth endpoints (429 when exceeded).

Quick start

Three requests to the first booking

Every example is working code against the production API https://minibi.pro. No sign-up, no tokens.

Find a master

Search by query and geo-radius: the query, coordinates and a radius in kilometers.

RequestGET /api/v1/masters/search

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

Response200 · 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"
    }
  ]
}

The card contains: id, name, username, rating, reviews_count, address, avatar. Then — GET /api/v1/masters/{id} for services.

Get available slots

Slots for a date across a set of services: the booking duration = the sum of service durations.

RequestGET /api/v1/masters/{id}/slots

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

Response200 · JSON

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

Parameters: service_ids (CSV, required), date YYYY-MM-DD, tz — offset in minutes, workspace_id.

Book the client

Guest flow without an account: first a confirmation code to the email, then the booking.

Step 1 · codePOST /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"}'

Step 2 · bookingPOST /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"
  }'

Step 1 response — { "sent": true }. Rate limit: 2 requests/sec for both endpoints. The create request sets up the client account (email + password) and a confirmed booking.

REST API

Catalog, booking and tasks over REST

Master catalog, services, slots, reviews, offers, events, guest booking, plus tasks and projects (via JWT) — JSON over HTTPS with cursor pagination, ETag/304 on GET and machine-readable {code, error} errors. Most GET endpoints are public — a token is only needed for personalized scenarios and the tasks and projects section.

Master catalog

GET /masters/search

Search by text, geo-radius (lat/lng/radius_km), bounding box (sw/ne) and min_rating. Pagination via page/limit or the after cursor.

GET /masters/autocomplete

Suggestions as you type — names, usernames, workspaces. From 3 characters, up to 20 results.

GET /masters/{id}

Master card: profile, services, workspaces. A profile hidden by privacy settings returns 404.

GET /masters/{id}/services

Active services: duration in minutes, price_from/price_to, the master's currency.

GET /masters/{id}/schedule

Weekly schedule by weekday, including workspace schedules.

GET /masters/{id}/available-days

Days with free windows in a from–to range — for a booking calendar. Plus next-slots — the nearest slot per service.

Reviews, offers, events

Reviews · /api/v1

GET /masters/{id}/reviews — reviews with a rating filter and limit/skip pagination; …/reviews/distribution — the count of 5…1 star ratings for a rating histogram.

Offers · /api/v2

GET /offers — a feed of published offers with cursor pagination and hashtags/category filters; GET /offers/{id} — a card with fulfillment methods; GET /masters/{id}/offers — the master's storefront. Responses are cached (ETag).

Events · /api/v2

GET /events/{id} — an event card (price, schedule, seats, participants); GET /masters/{id}/events — the list (cursor). With a Bearer token the card is extended with your participation status my_status.

Guest online booking

The main integration scenario: booking a client with a master without an account. Two requests — an email confirmation code (step 1 of the quick start), then the booking. The client account with a password is created automatically; for an existing user the booking is attached to their account after the code is verified. If the email already belongs to someone else's account — 409 user_already_exists, a guest booking never goes to someone else's account.

Field	Required	Description
master_id	yes	Master ID (hex24)
service_ids	yes	Array of service IDs — the booking duration equals the sum of services
start_time	yes	Start time, ISO 8601 UTC
client_name	yes	Client name
code	yes	Confirmation code from step 1 (valid for 15 minutes)
password, password_confirmation	yes	Password of the account being created: 8+ characters, an uppercase + a lowercase letter + a digit
client_email or client_phone	one of	Guest contact: email (the primary path) or an E.164 phone (legacy)
workspace_id	no	Workspace, if the master has several
note, source, utm_*	no	Note to the master, source tagging, UTM parameters
terms_acceptance, personal_data_consent	no*	Legal consents; versions — from GET /api/v1/legal/manifest

* We recommend always passing the consents: document versions come from GET /api/v1/legal/manifest.

Rules and limits

Error format

Every error is JSON with a machine-readable code and a message:

ErrorHTTP ≠ 2xx

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

HTTP	code	When
400	code_invalid	Invalid or expired confirmation code
400	legal_consent_required	Mandatory legal consents not provided
401	invalid_credentials	Wrong identifier or password
404	—	Resource not found or hidden by privacy settings
409	email_taken	Email already registered
409	user_already_exists	Guest email is taken by an existing account
409	time_slot_not_available	The selected time was just taken
429	too_many_attempts	Rate limit exceeded (2 requests/sec, burst 5)

Rate limits

Auth and guest mutations — 2 requests/sec, burst 5, then 429. Sending codes — a 60 sec cooldown and 3 codes per 5 minutes per identifier.

CORS

Server-side integrations work without restrictions. For browser-based ones we will add your origin on request — write to minibils2026@gmail.com.

Caching

GET responses return ETag / Last-Modified and support conditional requests — If-None-Match returns 304 without a body.

Pagination

Lists use cursor pagination: cursor.after + has_more; per-endpoint limits via the limit parameter.

All endpoints

All 52 platform endpoints: the public catalog and guest booking + tasks and projects via a JWT token. Full request and response schemas — in openapi.yaml.

Method	Path	Purpose
Masters — /api/v1
GET	/api/v1/masters/search	Master search: text, geo-radius or bbox, min_rating, pagination
GET	/api/v1/masters/autocomplete	Search suggestions from 3 characters
GET	/api/v1/masters/{master_id}	Master card: profile, services, workspaces
GET	/api/v1/masters/{master_id}/services	Active services of a master
GET	/api/v1/masters/{master_id}/schedule	Weekly working schedule
GET	/api/v1/masters/{master_id}/slots	Available slots for a date across a set of services
GET	/api/v1/masters/{master_id}/next-slots	Nearest available slot per service
GET	/api/v1/masters/{master_id}/available-days	Days with free windows within a date range
GET	/api/v1/masters/{master_id}/reviews	Master reviews (limit, skip, rating)
GET	/api/v1/masters/{master_id}/reviews/distribution	Distribution of 5…1 ratings
Landings & web booking — /api/public
GET	/api/public/masters	Paginated list of public masters
GET	/api/public/masters/popular	Popular masters (up to 8)
GET	/api/public/masters/{id}	Public master card (context=booking)
GET	/api/public/masters/{id}/workspaces	Workspaces for the booking page
GET	/api/public/masters/{id}/posts	Master's reference posts (cursor)
GET	/api/public/masters/{id}/reviews	Latest reviews (up to 10)
Offers & events — /api/v2
GET	/api/v2/offers	Feed of published offers (cursor, hashtags)
GET	/api/v2/offers/{id}	Offer card with fulfillment methods
GET	/api/v2/masters/{master_id}/offers	Master's offers
GET	/api/v2/events/{id}	Event card (with a token — my_status)
GET	/api/v2/masters/{master_id}/events	Master's active events
Guest booking
POST	/api/v1/guest/appointments	Guest online booking with a master (two steps)
POST	/api/v2/events/{id}/join-guest	Guest participation in an event
Authentication
POST	/api/v1/auth/register	Registration (email + password + consents)
POST	/api/v1/auth/login	Login with identifier and password
POST	/api/v1/auth/refresh-token	Exchange a refresh token for a new pair
POST	/api/v1/auth/send-code	Confirmation code to email
Tasks & projects — /api/v2 (JWT; creating a project is a Pro plan feature)
GET/POST	/api/v2/projects	Projects: list mine (owner/member) / create (Pro)
GET/PATCH/DELETE	/api/v2/projects/{id}	Project: card / update / delete
PUT	/api/v2/projects/{id}/statuses	Rewrite the set of project status columns
POST	/api/v2/projects/{id}/members	Add a project member
DELETE	/api/v2/projects/{id}/members/{user_id}	Remove a project member
POST	/api/v2/projects/{id}/invites	Invite by email / phone / username
GET	/api/v2/projects/{id}/report	Task report (from/to, plan vs actual)
POST	/api/v2/project_invites/{invite_id}/accept	Accept a project invitation
POST	/api/v2/project_invites/{invite_id}/decline	Decline a project invitation
GET	/api/v2/my/project_invites	My active project invitations
GET/POST	/api/v2/tasks	Tasks: list (project_id, filters) / create
GET	/api/v2/my/tasks	My open tasks
GET/PATCH/DELETE	/api/v2/tasks/{id}	Task: card / update / delete
GET	/api/v2/tasks/{id}/history	Status change history of a task
POST	/api/v2/tasks/{id}/attachments	Attach a file to a task
DELETE	/api/v2/tasks/{id}/attachments/{attachment_id}	Remove a task attachment
GET/POST	/api/v2/tasks/{id}/links	Task links: list / link (relates/blocks)
DELETE	/api/v2/tasks/{id}/links/{linked_task_id}	Remove a task link
GET/POST	/api/v2/tasks/{id}/comments	Task comments: list / add
PUT/DELETE	/api/v2/tasks/task_comments/{id}	Comment: edit / delete
GET	/api/v2/tasks/task_comments/{id}/replies	Replies to a comment
POST	/api/v2/tasks/media	Upload a photo for an attachment (multipart, up to 50 MB)
Service
GET	/api/v1/subscriptions/plans	Subscription plans
GET	/api/v1/legal/manifest	Legal document versions
GET	/api/v1/app/version	Minimum and current app versions

MCP for AI assistants

The whole platform as an AI agent tool

The platform MCP server: a base set of 35 tools — master search, bookings, tasks, chats, offers and events, personal events and online booking management. The full set (294 tools) — by request. The agent works with the same rights and limits as the app.

Token

Connect in a minute

1 Create a token: open the web cabinet minibi.pro/cabinet → Settings → Integration tokens → Create. The token is shown once — copy it.
2 Add the server to your MCP client (Cursor, ZCode, Claude and others):

MCP client configmcp.json

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

3 Done: the tools work on your behalf with the same rights as the app.

The token starts with mbk_… — you can keep up to 5 active ones. Deleting a token in the cabinet revokes access instantly.

Session example

Working with the booking calendar right after connecting:

MCP sessiontools/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 stack: http://localhost:8085/mcp.

Ready-made artifacts

Download and get to work

OpenAPI 3.0 — openapi.yaml

The API specification in OpenAPI 3.0 — catalog, online booking, tasks and projects: parameters, response schemas, error codes. Imports into Postman, Insomnia and GPT Actions with no changes.

Agent Skill — minibi-api

A ready-made skill for AI agents: master search and guest booking.

Download the zip archive
Connect it to your AI agent (in Claude: Settings → Capabilities → Skills)
Upload the archive

FAQ

Frequently asked questions

Do I need a token for master search?

No. All GET endpoints of the catalog, reviews, offers and events are public and work without authorization. A Bearer token only personalizes the output: search considers the user's interests, and events get the my_status field.

What are the API limits?

Authentication and guest mutations (send-code, guest/appointments, join-guest) — 2 requests/sec with burst 5, 429 when exceeded. Public GETs are not limited as aggressively, but we recommend caching responses (ETag / Cache-Control are already served).

How do I get a Bearer token for MCP?

Create it yourself in the web cabinet (minibi.pro/cabinet): Settings → Integration tokens → Create. The mbk_… token is shown once — copy it. The limit is 5 active tokens; deleting a token revokes access.

How is versioning handled?

The version is in the path: /api/v1 and /api/v2. Backward-compatible changes (new fields, new endpoints) happen without bumping the version; breaking changes — only in a new version, announced in advance.

Where to write if something does not work?

minibils2026@gmail.com — we will look into the request, help with endpoints and add your origin to CORS for browser integrations.