MTB API Documentation

Добро пожаловать в документацию MTB API. Здесь описаны все доступные эндпоинты, WebSocket Gateway события, OAuth2 авторизация и примеры использования.

Base URL: https://api.metalib.xyz — Все API запросы отправляются на этот адрес.

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

Для начала работы с API тебе нужен токен авторизации. Получи его через OAuth2 или используй токен бота.

GET Пример запроса

curl -X GET https://api.metalib.xyz/api/users/@me \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Ответ

{
  "id": "1476197534295711744",
  "username": "player",
  "discriminator": "0",
  "avatar": "a1b2c3d4e5f6",
  "email": "player@example.com",
  "flags": 0,
  "premium_type": 0
}

Форматы данных

Все запросы и ответы используют JSON
ID объектов — строки (Snowflake формат)
Даты в формате ISO 8601
Content-Type: application/json

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

Текущая версия API: v1. API обратно совместимо — мы не удаляем поля без предупреждения.

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

Все запросы к API должны включать заголовок Authorization с токеном доступа.

Типы токенов

TOKEN Пользовательский токен

Получается при входе через OAuth2. Рспользуется для действий от имени пользователя.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

BOT Токен бота

Создаётся в панели разработчика. Рспользуется для ботов и интеграций.

Authorization: Bot MTB.xxxxxxxxxxxxxxxxxxxx

Получение токена

POST /api/auth/login

Авторизация по email и паролю. Возвращает токен доступа.

Параметр	Тип	Описание
email*	string	Email пользователя
password*	string	Пароль

{
  "token": "mtb_RBkMGBy7FRlyL7Gl..."
}

Никогда не передавай токен третьим лицам. Если токен скомпрометирован — немедленно смени пароль.

Rate Limits

API использует rate limiting для предотвращения злоупотреблений. Превышение лимита вернёт статус 429 Too Many Requests.

Заголовки

Заголовок	Тип	Описание
X-RateLimit-Limit	int	Максимум запросов в окне
X-RateLimit-Remaining	int	Оставшиеся запросы
X-RateLimit-Reset	float	Unix timestamp сброса лимита
X-RateLimit-Bucket	string	Уникальный ID bucket'а
Retry-After	int	Секунд до следующего запроса (при 429)

Стратегия

Глобальный лимит: 50 запросов/секунду
Per-route лимиты зависят от эндпоинта
При получении 429 — ждать Retry-After секунд

Совет: используй заголовки rate limit для проактивного throttling вместо ожидания ошибки 429.

Users

Эндпоинты для работы с пользователями.

GET /api/users/@me

Возвращает текущего авторизованного пользователя.

{
  "id": "1476197534295711744",
  "username": "player",
  "discriminator": "0",
  "avatar": "a1b2c3d4e5f6",
  "email": "player@example.com",
  "verified": true,
  "flags": 0
}

GET /api/users/{user_id}

Возвращает информацию о пользователе по ID.

Параметр	Тип	Описание
user_id*	snowflake	ID пользователя

PATCH /api/users/@me

Обновить профиль текущего пользователя.

Параметр	Тип	Описание
username	string	Новое имя (2-32 символа)
avatar	string	Base64 изображение аватара

Guilds (Серверы)

Эндпоинты для управления серверами.

GET /api/guilds/{guild_id}

Рнформация о сервере.

{
  "id": "1476200000000000000",
  "name": "Gamers Hub",
  "icon": "abc123def456",
  "owner_id": "1476197534295711744",
  "member_count": 42,
  "channels": [...]
}

POST /api/guilds

Создать новый сервер.

Параметр	Тип	Описание
name*	string	Название сервера (2-100 символов)
icon	string	Base64 изображение иконки

DELETE /api/guilds/{guild_id}

Удалить сервер. Только для владельца.

Channels

Эндпоинты для работы с каналами.

GET /api/channels/{channel_id}

Рнформация о канале.

Типы каналов

Тип	Значение	Описание
GUILD_TEXT	0	Текстовый канал сервера
DM	1	Личные сообщения
GUILD_VOICE	2	Голосовой канал
GROUP_DM	3	Групповые ЛС
GUILD_CATEGORY	4	Категория каналов

Messages

Отправка и получение сообщений.

GET /api/channels/{channel_id}/messages

Получить сообщения канала. Макс. 100 за запрос.

Query	Тип	Описание
limit	int	1-100, по умолчанию 50
before	snowflake	Сообщения до этого ID
after	snowflake	Сообщения после этого ID

POST /api/channels/{channel_id}/messages

Отправить сообщение в канал.

Параметр	Тип	Описание
content*	string	Текст (до 2000 символов)
nonce	string	Уникальный ID для дедупликации
tts	bool	Text-to-speech

// Пример
POST /api/channels/123456/messages
{
  "content": "Привет! 🚀"
}

DELETE /api/channels/{channel_id}/messages/{message_id}

Удалить сообщение. Свои — всегда, чужие — с правами MANAGE_MESSAGES.

Invites

Управление ссылками-приглашениями.

GET /api/invites/{code}

Рнформация о приглашении по коду.

POST /api/channels/{channel_id}/invites

Создать приглашение в канал.

Параметр	Тип	Описание
max_age	int	Время жизни в секундах (0 = бессрочно)
max_uses	int	Макс. использований (0 = безлим.)

WebSocket Gateway

Real-time соединение для получения событий. Подключение через WebSocket.

Gateway URL: wss://web.metalib.xyz/gateway

Подключение

const ws = new WebSocket('wss://web.metalib.xyz/gateway');

ws.onopen = () => {
  // Отправить IDENTIFY
  ws.send(JSON.stringify({
    op: 2,
    d: {
      token: "YOUR_TOKEN",
      properties: {
        os: "linux",
        browser: "chrome",
        device: ""
      }
    }
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.t, data.d);
};

Opcodes

Code	Название	Описание
0	Dispatch	Событие от сервера
1	Heartbeat	Поддержание соединения
2	Identify	Авторизация при подключении
7	Reconnect	Сервер просит переподключиться
9	Invalid Session	Сессия недействительна
10	Hello	heartbeat_interval при подключении
11	Heartbeat ACK	Ответ на heartbeat

Heartbeat

После получения op: 10 (Hello) начинай отправлять heartbeat с указанным интервалом:

// Heartbeat каждые heartbeat_interval мс
setInterval(() => {
  ws.send(JSON.stringify({ op: 1, d: lastSequence }));
}, heartbeatInterval);

Gateway Events

События, получаемые через WebSocket Gateway.

Основные события

Событие	Описание
READY	Начальные данные после IDENTIFY
MESSAGE_CREATE	Новое сообщение
MESSAGE_UPDATE	Сообщение отредактировано
MESSAGE_DELETE	Сообщение удалено
GUILD_CREATE	Присоединение к серверу
GUILD_DELETE	Выход с сервера
CHANNEL_CREATE	Создан новый канал
CHANNEL_UPDATE	Канал обновлён
CHANNEL_DELETE	Канал удалён
TYPING_START	Пользователь печатает
PRESENCE_UPDATE	Обновление статуса
VOICE_STATE_UPDATE	Рзменение голосового состояния
GUILD_MEMBER_ADD	Новый участник сервера
GUILD_MEMBER_REMOVE	Участник покинул сервер

Пример MESSAGE_CREATE

{
  "t": "MESSAGE_CREATE",
  "s": 42,
  "op": 0,
  "d": {
    "id": "1476300000000000000",
    "channel_id": "1476200000000000001",
    "author": {
      "id": "1476197534295711744",
      "username": "player"
    },
    "content": "Привет всем! 👋",
    "timestamp": "2026-02-25T12:00:00.000Z"
  }
}

OAuth2

Авторизация сторонних приложений через OAuth2.

Authorize Flow

Перенаправь пользователя на /oauth2/authorize
Пользователь разрешает доступ
Получаешь code на redirect_uri
Обмениваешь code на access_token

GET /oauth2/authorize

Страница авторизации OAuth2.

Query	Тип	Описание
client_id*	snowflake	ID приложения
redirect_uri*	string	URL для callback
response_type*	string	Всегда `code`
scope*	string	Запрашиваемые права

Scopes

Scope	Описание
identify	Базовая информация (id, username, avatar)
email	+ адрес email
guilds	Список серверов пользователя
guilds.join	Добавление на сервер
messages.read	Чтение сообщений

Коды ошибок

API возвращает стандартные HTTP статус-коды и дополнительные коды ошибок MTB.

HTTP статус-коды

Код	Описание
200	OK — Запрос выполнен
201	Created — Ресурс создан
204	No Content — Успех без тела ответа
400	Bad Request — Некорректный запрос
401	Unauthorized — Не авторизован
403	Forbidden — Недостаточно прав
404	Not Found — Ресурс не найден
429	Too Many Requests — Rate limit
500	Internal Server Error
502	Gateway Unavailable

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

{
  "code": 50001,
  "message": "Missing Access",
  "errors": {}
}

Коды ошибок MTB

Код	Описание
10001	Unknown Account
10003	Unknown Channel
10004	Unknown Guild
10008	Unknown Message
30001	Maximum guilds reached
40001	Unauthorized — invalid token
50001	Missing Access
50013	Missing Permissions
50035	Invalid Form Body