Начало

Обзор

Документация для разработчиков Min (MinChat): REST API, realtime-события и Bot API, совместимый с Telegram.

Min — мессенджер с веб-, десктоп- и Android-клиентами. Всё, что делают официальные клиенты, идёт через описанный здесь HTTP API: JSON REST API под /api, Pusher-совместимый WebSocket для realtime-событий и отдельный Bot API, совместимый с Telegram.

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

Войдите, получите список чатов и отправьте сообщение:

# 1. Sign in (identifier-first wizard)
TICKET=$(curl -s -X POST https://minchatapp.com/api/auth/start \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -d '{"identifier":"anna@example.com"}' | jq -r .ticket)

TOKEN=$(curl -s -X POST https://minchatapp.com/api/auth/password \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -d "{\"ticket\":\"$TICKET\",\"password\":\"Secret123\"}" | jq -r .token)

# 2. List conversations
curl -s https://minchatapp.com/api/conversations \
  -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'

# 3. Send a message
curl -s -X POST https://minchatapp.com/api/conversations/12/messages \
  -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"content":"Hello from the API 👋"}'

const API = 'https://minchatapp.com/api';

async function call(path, { token, method = 'GET', body } = {}) {
  const res = await fetch(API + path, {
    method,
    headers: {
      Accept: 'application/json',
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await res.json();
  if (!res.ok) throw Object.assign(new Error(data.message), { code: data.code, status: res.status });
  return data;
}

const { ticket } = await call('/auth/start', { method: 'POST', body: { identifier: 'anna@example.com' } });
const { token } = await call('/auth/password', { method: 'POST', body: { ticket, password: 'Secret123' } });
const chats = await call('/conversations', { token });
await call(`/conversations/${chats[0].id}/messages`, { token, method: 'POST', body: { content: 'Hello 👋' } });

import requests

API = "https://minchatapp.com/api"
s = requests.Session()
s.headers["Accept"] = "application/json"

ticket = s.post(f"{API}/auth/start", json={"identifier": "anna@example.com"}).json()["ticket"]
token = s.post(f"{API}/auth/password", json={"ticket": ticket, "password": "Secret123"}).json()["token"]
s.headers["Authorization"] = f"Bearer {token}"

chats = s.get(f"{API}/conversations").json()
msg = s.post(f"{API}/conversations/{chats[0]['id']}/messages", json={"content": "Hello 👋"}).json()
print(msg["id"])

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

Все защищённые методы требуют токен Sanctum в Authorization: Bearer <token>. Токены выдают методы входа (пароль, одноразовый код, QR, Google OAuth); сами они не истекают. Каждый токен — сессия, которую пользователь видит и может завершить в Настройки → Устройства (GET /api/user/sessions). Заблокированный аккаунт получает 403 с code: "banned".

Необязательные заголовки клиента, подписывающие сессию:

Все способы входа — в разделе Аутентификация.

Ошибки#

Ошибки приходят в едином конверте. code — стабильный машинный идентификатор (domain.snake_case); error и message — один и тот же английский текст. Ошибки валидации (422) добавляют errors (поле → сообщения) и error_codes (поле → коды). Полный каталог — на странице Ошибки.

{
  "success": false,
  "code": "validation.failed",
  "error": "The given data was invalid.",
  "message": "The given data was invalid.",
  "errors": { "send_at": ["The time is too far in the future."] },
  "error_codes": { "send_at": ["validation.failed"] }
}

Ограничения частоты#

Лимиты задаются на маршрут и пользователя (или IP для публичных маршрутов). У каждого метода в справочнике указан лимит, например 60/мин. При превышении — 429 с code: "common.throttled" и стандартными заголовками Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining. Маршруты без явного лимита тоже защищены; не опрашивайте чаще раза в секунду.

Пагинация#

Единой схемы нет — каждый список использует подходящий курсор:

Соглашения#

• id — целые числа; id вложений — строки UUID.
• Время — ISO 8601 в UTC (например, 2026-10-22T09:06:13+00:00 или …000000Z). В Bot API — Unix time (date).
• Булевы значения в multipart можно передавать как 1/0.
• Передавайте Accept: application/json, чтобы ошибки возвращались в JSON.
• Передавайте client_id (UUID) с сообщениями, чтобы повторы были идемпотентны.
• URL вложений (/storage/media/…) требуют тот же Bearer — передавайте его только на хост Min.

Версионирование#

Версии в URL нет. API развивается аддитивно: новые поля и методы могут появиться в любой момент — игнорируйте незнакомые поля. Ломающих изменений избегаем; legacy-методы (например, /api/login, /api/files/…) остаются для старых клиентов. Нативные клиенты получают политику обновлений через GET /api/client-updates (update: soft|force).

Публичные веб-адреса#