JSON API · без ключей

Публичное API

Мемы, теги, комментарии, лайки и реакции. Без регистрации и API-ключей — только лимиты по IP.

Base URL https://смешнявки.рф JSON · UTF-8 Лимиты по IP

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

Три запроса, чтобы проверить API без документации.

01

Случайный мем

curl https://смешнявки.рф/api/random-meme
02

Комментарии

curl "https://смешнявки.рф/api/comments/123?limit=10"
03

Лайк

curl -X POST https://смешнявки.рф/api/like/123

Общие правила

API отдаёт JSON и не требует авторизации для чтения. Данные — публичные мемы, теги и одобренные комментарии.

ФорматJSON, UTF-8
ЧтениеБез авторизации
ЗаписьCSRF для загрузки
ЛимитыПо IP, Redis

Публичные GET-эндпоинты не требуют CSRF-токена. POST /api/upload требует анонимную сессию и токен с /uploads. CORS не настроен: браузерные запросы с других origin не пройдут.

Эндпоинты

Пять групп: загрузка, мемы, лайки, реакции и комментарии.

POST /api/upload

Загрузка изображения в multipart/form-data. Мем создаётся неопубликованным и ждёт модерации. Нужен CSRF-токен с формы /uploads.

ПолеТипОписание
file или imagefilePNG, JPG, GIF, WEBP, BMP. До 20 МБ, сторона ≤ 3840 px, всего ≤ 8,3 Мп (например, 3840×2160 или 2160×3840).
csrf_tokenstringТокен из формы /uploads. Можно передать заголовком X-CSRFToken.
titlestringНеобязательно, до 255 символов.
descriptionstringНеобязательно, до 5000 символов.
tagsstringНеобязательно, через запятую: до 10 тегов по 32 символа.
curl -c cookies.txt https://смешнявки.рф/uploads

curl -b cookies.txt -X POST https://смешнявки.рф/api/upload \
  -F "csrf_token=CSRF_TOKEN_ИЗ_ФОРМЫ" \
  -F "file=@meme.png" \
  -F "title=Смешной мем" \
  -F "description=Описание" \
  -F "tags=кот,смешное"
// 201 Created
{
  "success": true,
  "message": "Файл загружен",
  "meme_id": 123,
  "filename": "abc123.avif",
  "warning": "Похожий мем уже есть (#456)"
}

Лимит: 5 загрузок в минуту. Файл конвертируется в AVIF, EXIF/XMP удаляются. Поле warning приходит только при похожем меме.

Мемы

Случайный, дня и по файлу

Только опубликованные мемы. Если опубликованных нет — 404.

GET /api/random-meme
{"filename": "abc123.avif", "title": "Смешной мем"}
GET /api/meme-of-the-day

Один и тот же мем на весь текущий день, кэш до конца дня.

{"id": 123, "filename": "abc123.avif", "title": "Смешной мем"}
GET /api/meme-id?filename=abc123.avif
{"id": 123}
GET /api/all-tags

Все теги с количеством использований. Для /api/meme-id и остальных методов мемов учитываются только опубликованные мемы.

{"tags": [{"name": "кот", "count": 42}]}
Лайки

Только счётчик

Лайк не отменяется: каждый запрос увеличивает счётчик. IP в базе не хранится.

POST /api/like/<meme_id>

Только same-origin: cross-site запросы получают 403 по Sec-Fetch-Site / Origin.

// 200
{"liked": true, "count": 43}

// 404 — мем не найден
// 429 — больше 3 лайков за 30 секунд
GET /api/like-status/<meme_id>
{"liked": false, "count": 43}

liked всегда false: без хранения идентичности узнать «лайкнул ли я» нельзя.

Реакции

Эмодзи-счётчики

Принимается эмодзи или стабильный код. В базе хранится код, наружу отдаётся эмодзи.

POST /api/reaction/<meme_id>
curl -X POST https://смешнявки.рф/api/reaction/123 \
  -H "Content-Type: application/json" \
  -d '{"reaction": "🗿"}'

Допустимые реакции: 🗿 🔥 🥺 👏 💔 🤡 💀. Вместо эмодзи можно передать код: moai, fire, pleading, clap, broken_heart, clown, skull.

// 200
{"reaction": "🗿", "count": 5, "counts": {"🗿": 5, "🔥": 0, "🥺": 0, "👏": 0, "💔": 0, "🤡": 0, "💀": 0}}

// 400 — неизвестная реакция
// 404 — мем не найден или не опубликован
// 429 — больше 3 реакций за 30 секунд
GET /api/reaction-status/<meme_id>
{"counts": {"🗿": 5, "🔥": 0, "🥺": 0, "👏": 0, "💔": 0, "🤡": 0, "💀": 0}}
Комментарии

Отправка и дерево одобренных

Новые комментарии уходят на модерацию. Публично отдаются только одобренные, с ответами и пагинацией по корневым комментариям.

POST /api/comment/<meme_id>

Тело — JSON. nickname до 50 символов, по умолчанию «Аноним». text обязателен, до 2000 символов, HTML вырезается. parent_id — id одобренного комментария того же мема.

curl -X POST https://смешнявки.рф/api/comment/123 \
  -H "Content-Type: application/json" \
  -d '{"nickname": "Аноним", "text": "Отличный мем!"}'
// 201 Created
{"success": true, "message": "Комментарий отправлен, ожидает проверки"}

// 400 — пустой текст, >2000 символов, parent_id не число
// 404 — мем не найден
// 429 — чаще 1 комментария в минуту или повтор текста за 5 минут

// Несуществующий или неодобренный parent_id просто игнорируется:
// комментарий станет корневым.
GET /api/comments/<meme_id>?limit=10&cursor=123

Только одобренные комментарии. limit — 1…50, по умолчанию 10. cursor — id последнего корневого комментария с предыдущей страницы.

// 200
{
  "comments": [
    {
      "id": 12,
      "parent_id": null,
      "nickname": "Аноним",
      "text": "Отличный мем!",
      "created_at": "12.11.2026 01:20",
      "depth": 0,
      "replies": []
    }
  ],
  "next_cursor": 12
}

next_cursor равен null, когда страниц больше нет. Дата — в формате ДД.ММ.ГГГГ ЧЧ:ММ.

HTML-страницы

Не JSON, но полезно для интеграций и ссылок.

РоутОписание
GET /Галерея и мем дня. ?sort=new|likes|views|random|hot, ?cursor=
GET /meme/<id>Страница мема: og-image, canonical, JSON-LD, похожие, комментарии
GET /search?q=Поиск: FULLTEXT в MySQL, FTS5 в SQLite, fallback ILIKE
GET /tagsОблако тегов с количеством
GET /tag/<name>Мемы по тегу
GET /uploadsФорма загрузки и CSRF-токен
GET /favorites?ids=Избранное: id через запятую, максимум 100
GET /history?ids=Просмотренные: id через запятую, максимум 50
GET /randomРедирект на случайный мем
GET /statsПубличная статистика
GET /feed.xmlRSS 2.0, 30 последних мемов
GET /sitemap.xmlSitemap, кэш 1 час
GET /image-sitemap.xmlImage sitemap для Google
GET /robots.txtRobots и ссылки на sitemap
GET /privacyПолитика конфиденциальности
GET /api-docsЭта страница

Лимиты

Считаются по IP и хранятся в Redis/Valkey. При превышении — 429.

ЗапросЛимит
POST /api/upload5 в минуту
POST /api/like/<id>3 за 30 секунд
POST /api/reaction/<id>3 за 30 секунд
POST /api/comment/<id>1 в минуту
Остальные GET без отдельного лимита200 в день, 50 в час

Ошибки

Ошибки ввода и запреты возвращаются JSON-объектом {"error": "..."}. Страницы 404, 413, 429 и 500 отдаются как HTML.

КодКогда
400Невалидное тело, пустой текст, слишком длинные поля, нет/неверный CSRF-токен
403Cross-site лайк по Sec-Fetch-Site / Origin
404Мем или комментарий не найден, нет опубликованных мемов
413Файл больше 20 МБ
429Превышен лимит запросов
500Внутренняя ошибка сервера

HTMX-фрагменты: запросы с HX-Request: true к галерее, тегам, поиску, избранному и истории возвращают HTML-фрагменты вместо полных страниц.