API

Это перевод. Обязательной является версия на немецком языке. Там, где этот текст от неё отличается, действует немецкий текст. Язык можно переключить внизу страницы.

Содержание

Обзор

v2 позволяет твоим собственным программам общаться с tellmelo: один ключ на запрос, в ответ JSON, все списки листаются одинаково. Действуют те же правила, что и в приложении.

Каждый путь начинается с /api/v2 по адресу этого сервера.
Запросы и ответы — JSON в UTF-8. Имена полей, коды и значения английские и остаются английскими.
Ключ действует как твой аккаунт: чего ты не видишь в приложении, он тоже не прочитает.

https://tellmelo.com/api/v2

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

Создай ключ в «Настройки → Приложение и данные → API» и скопируй его. Он показывается только один раз.
Вызови с ним корень. В ответе — версия, права ключа и сколько запросов осталось в этой минуте.
Все пути работают одинаково: ключ в заголовке, в ответ JSON, для списков items и next.

curl -H "Authorization: Bearer tm_key_…" https://tellmelo.com/api/v2

{
  "name": "tellmelo",
  "version": "2.10",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/legal/api",
  "spec": "/api/v2/openapi.json"
}

Дальше: /me для твоего профиля, /posts для публичных постов, /feed для твоей ленты.

Попробовать

Выбери задачу, заполни поля и скопируй запрос или отправь его отсюда. Перед записью мы спросим. Код читает ключ из TELLMELO_KEY.

Задача

read Версия API и название этого сервера.

curl \
  -H "Authorization: Bearer $TELLMELO_KEY" \
  "https://tellmelo.com/api/v2"

Твой ключХранится только на этой странице, пока ты её не закроешь.

Твой ключ

Один ключ на аккаунт. Он начинается с tm_key_ и показывается только один раз. Потерял? Создай новый; старый перестанет работать.

Ты создаёшь его в «Настройки → Приложение и данные → API». Он передаётся в заголовке запроса:

curl -H "Authorization: Bearer tm_key_…" \
  https://tellmelo.com/api/v2/posts

Или, если так удобнее, в отдельном заголовке:

curl -H "X-Tellmelo-Key: tm_key_…" https://tellmelo.com/api/v2

Не в URL: он попал бы в логи и в историю браузера.

Тот же ключ загружает изображения: каждый url ведёт на /api/media; передавай ключ в заголовке и там.

curl -H "Authorization: Bearer tm_key_…" \
  -o picture.webp "https://tellmelo.com/api/media?id=…"

Что может ключ

У ключа одно из двух прав, и у каждого пути ниже указано, какое ему нужно:

read: чтение. Публичные посты, профили, группы и теги, а также твоя лента, уведомления и сообщения.
write: действия. Публиковать, отвечать, голосовать, отправлять сообщения, подписываться, вступать, блокировать, отмечать уведомления прочитанными.

Чего не может ни один ключ

Ни один ключ не достаёт до пароля, адреса эл. почты, типа аккаунта, места, роли, удаления, сеансов, push-устройств и других ключей, а также до администрирования и руководства группами. Что защищает пароль, ни один ключ не может.

Запросы и ответы

JSON везде. Каждый ответ — application/json в UTF-8, включая ошибки. Только изображения приходят изображениями.
Что ты отправляешь. POST передаёт свои поля как JSON в теле. Если поле есть и в URL, побеждает тело.
Время — миллисекунды с 1 января 1970 года, UTC.
ID — строки. Сравнивай их только целиком.
Каждое поле присутствует всегда. Отсутствующее — null; списки могут быть пустыми.
Тексты — обычный текст, ровно как написаны. #теги, @имена и ссылки остаются как есть, как и собственные эмодзи сервера в виде :имя:; их картинки перечислены в /emojis.
Изображения — относительные адреса, /api/media?id=…. Без ключа в заголовке получишь 401.

Страницы

Каждый список принимает limit и cursor и отвечает items и next. Отправь next обратно как cursor, чтобы получить следующую страницу; если next пуст, всё. Курсор непрозрачен: не разбирай его и не составляй сам.

{ "items": [ … ], "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx" }

curl -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts?limit=20&cursor=MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"

Без limit — 20 записей, максимум 50. Некоторые списки не листаются; их next всегда null.

Только новое

Каждый ответ несёт ETag. Отправь его в следующий раз как If-None-Match: если ничего не изменилось, получишь 304 без тела.

ETag: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc"
If-None-Match: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc"  →  304

Исключения: у /feed нет ETag, потому что его порядок всё время меняется, а записи никогда не отвечают 304.

Лимиты

Ключ может делать 120 запросов в минуту, 600 с тарифом «Организация», если администрация не задала иначе. Сверх этого ты получишь 429, и ничего не выполнится. Подожди минуту и отправь запрос снова.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1758624060

Записи также учитываются в лимитах приложения, например сколько постов за несколько минут. Это тоже отвечает 429 с rate_limited.

Заголовки

Кроме ключа, никакие заголовки не обязательны.

Что ты отправляешь

Заголовок	Значение
`Authorization`	Несёт ключ: `Bearer tm_key_…`. Обычный способ.
`X-Tellmelo-Key`	Ключ, как альтернатива `Authorization`.
`Content-Type`	`application/json`, для запроса с телом.
`If-None-Match`	`ETag` последнего ответа. Если с тех пор ничего не изменилось, ответ — `304` без тела.

Что приходит в ответ

Заголовок	Значение
`ETag`	Отпечаток этого ответа (`W/`). Отправь его обратно как `If-None-Match`.
`X-RateLimit-Limit`	Сколько запросов в минуту может делать этот ключ.
`X-RateLimit-Remaining`	Сколько из них осталось в текущей минуте.
`X-RateLimit-Reset`	Когда начнётся следующая минута, в секундах с 1970 года, UTC.
`X-Tellmelo-Scope`	Что может этот ключ: `read` или `read write`.
`Retry-After`	При `429`: сколько секунд подождать перед новым запросом.
`WWW-Authenticate`	При `401` без ключа: `Bearer`.
`Cache-Control`	`no-store`: ни один прокси не может кэшировать ответ. Проверить его ты всё равно можешь по `ETag`.

Когда что-то не работает

Ошибки приходят в JSON: фиксированный английский код в error для программы и фраза в message для людей, плюс соответствующий код статуса. Сравнивай только код; фраза может меняться.

{ "error": "rate_limited",
  "message": "Too many requests. Try again in a minute.",
  "limit": 120 }

Некоторые ошибки несут ещё одно поле: docs при 401 из-за отсутствия ключа, limit при 429.

Статус	Код	Значение
`400`	`bad_request`	Запрос нельзя прочитать, не хватает обязательного поля или значение недопустимо.
`401`	`key_missing`	В заголовке нет ключа.
`401`	`key_invalid`	Ключ недействителен: опечатка, замена или аккаунт заблокирован.
`401`	`unauthorized`	Отклонено как без входа, по причине, не связанной с ключом.
`403`	`scope_missing`	У ключа нет нужного права, обычно `write`.
`403`	`account_data_locked`	Данные аккаунта, такие как пароль, адрес эл. почты или удаление, ключам недоступны.
`403`	`forbidden`	Твоему аккаунту это нельзя, например из-за отозванного права или блокировки.
`404`	`unknown_path`	Такого пути нет или нет с этим методом.
`404`	`not_found`	Не найдено, или тебе нельзя это видеть.
`409`	`conflict`	Конфликтует с уже существующим, например имя занято.
`413`	`too_large`	Слишком велико для этого сервера.
`422`	`unprocessable`	Читается, но в таком виде невозможно.
`429`	`rate_limited`	Слишком много запросов. Ничего не произошло; подожди и попробуй снова.
`500`	`internal_error`	На сервере что-то пошло не так.

Версии

Версия указана в пути. Пока там v2, пути и поля остаются прежними; новое только добавляется.

Дополнения увеличивают второе число. У каждого пути указано, с какой версии он есть.

/api/v1/ больше нет: старые пути отвечают 410 и называют новый путь в теле.

Конечные точки

Все пути одним взглядом, затем каждый с примером.

Путь	Право	Для чего
Вход
GET`/api/v2`	`read`	Версия API и название этого сервера.
Посты
GET`/api/v2/posts`	`read`	Публичные посты, сначала новые.
GET`/api/v2/posts/{id}`	`read`	Один пост по его `id`.
POST`/api/v2/posts`	`write`	Опубликовать пост.
DELETE`/api/v2/posts/{id}`	`write`	Удалить один из своих постов.
Ответы
GET`/api/v2/posts/{id}/replies`	`read`	Ответы на пост, без заблокированных аккаунтов.
POST`/api/v2/posts/{id}/replies`	`write`	Ответить на пост.
Опросы
POST`/api/v2/posts/{id}/vote`	`write`	Принять участие в опросе.
Профили
GET`/api/v2/profiles/{handle}`	`read`	Профиль по его короткому имени.
GET`/api/v2/profiles/{handle}/posts`	`read`	Публичные посты одного профиля, сначала новые.
Группы
GET`/api/v2/communities`	`read`	Открытые группы этого сервера.
GET`/api/v2/communities/{id}`	`read`	Одна группа по её `id`.
GET`/api/v2/communities/{id}/posts`	`read`	Публичные посты одной группы, сначала новые.
Обзор
GET`/api/v2/tags`	`read`	Теги, которые сейчас в ходу.
GET`/api/v2/search`	`read`	Поиск по постам, именам, коротким именам и тегам.
GET`/api/v2/emojis`	`read`	Собственные эмодзи сервера с адресами их картинок.
Твой аккаунт
GET`/api/v2/me`	`read`	Твой собственный профиль с `id`, который ждут остальные пути.
GET`/api/v2/feed`	`read`	Твоя собственная лента в том виде, как её собирает приложение.
Уведомления
GET`/api/v2/notifications`	`read`	Твои уведомления, сначала новые.
POST`/api/v2/notifications/read`	`write`	Отметить уведомления прочитанными.
Сообщения
GET`/api/v2/conversations`	`read`	Твой ящик: по строке на переписку, сначала самая свежая.
GET`/api/v2/conversations/{with}/messages`	`read`	Сообщения одной переписки, сначала новые.
POST`/api/v2/conversations/{with}/messages`	`write`	Отправить сообщение в переписку.
POST`/api/v2/conversations/{with}/read`	`write`	Отметить все сообщения переписки прочитанными.
Связи
POST`/api/v2/relations`	`write`	Отметить, сохранить, репостнуть, подписаться, вступить, заблокировать, скрыть — в зависимости от `kind`.

Вход

Первый запрос любой программы: работает ли ключ и что ему можно?

GET`/api/v2`

Версия API и название этого сервера.

Право read
с ETag
с v2.0

Без слеша в конце: /api/v2/ перенаправляет на /api/v2 с 308, и не каждая программа следует за этим.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2"

Ответ

Отвечает одним Service.

Пример

{
  "name": "tellmelo",
  "version": "2.10",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/legal/api",
  "spec": "/api/v2/openapi.json"
}

Возможные статусы: 200304401429

Посты

Читать публичные посты, публиковать свои и снова удалять их.

GET`/api/v2/posts`

Публичные посты, сначала новые.

Право read
с пагинацией
с ETag
с v2.0

На публичных путях counts.likes и counts.reposts всегда 0, а pinned — false.

Посты в группах находятся не здесь, а в /communities/{id}/posts.

Параметры

Имя	Тип	Значение
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.
`cursor`в query	`string`необязательно	`next` из предыдущего ответа. Без него — с начала.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts?limit=20"

Ответ

Отвечает страницей Post в виде `items` и `next`.

Пример

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Возможные статусы: 200304401429

GET`/api/v2/posts/{id}`

Один пост по его id.

Право read
с ETag
с v2.0

На публичных путях counts.likes и counts.reposts всегда 0, а pinned — false.

Посты в группах находятся не здесь, а в /communities/{id}/posts.

Параметры

Имя	Тип	Значение
`id`в пути	`string`обязательно	`id` поста.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"

Ответ

Отвечает одним Post.

Пример

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "text": "The bees are back in the garden 🐝 #garden",
  "kind": "poll",
  "author": {
    "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
    "handle": "mara",
    "name": "Mara 🌻",
    "verified": true,
    "accountKind": "person"
  },
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening"
  },
  "media": [
    {
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "image",
      "poster": null
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": 1758710400000,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "createdAt": 1758624000000
}

Возможные статусы: 200304400401404429

POST`/api/v2/posts`

Опубликовать пост.

Право write
с v2.0

Посту нужен текст или опрос. Длину, варианты опроса и темп задаёт сервер; сверх этого ты получишь 400 или 429.

Прикреплять изображения через API пока нельзя, только в приложении.

Параметры

Имя	Тип	Значение
`text`в теле	`string`необязательно	Текст поста, ответа или сообщения.
`community`в теле	`string`необязательно	`id` группы, в которую идёт пост. Без него — вне всех групп.
`quotes`в теле	`string`необязательно	`id` поста, который цитирует этот.
`poll`в теле	`string[]`необязательно	Варианты ответа списком текстов.

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

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"The bees are back in the garden 🐝 #garden"}' \
  "https://tellmelo.com/api/v2/posts"

Ответ

Отвечает одним Created.

Пример

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

Возможные статусы: 200400401403429

DELETE`/api/v2/posts/{id}`

Удалить один из своих постов.

Право write
с v2.0

Параметры

Имя	Тип	Значение
`id`в пути	`string`обязательно	`id` поста.

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

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"

Ответ

Отвечает одним Ok.

Пример

{
  "ok": true
}

Возможные статусы: 200400401403404429

Ответы

Ответы под постом, списком с parentId.

GET`/api/v2/posts/{id}/replies`

Ответы на пост, без заблокированных аккаунтов.

Право read
с пагинацией
с ETag
с v2.0

Список плоский и идёт в порядке написания; parentId превращает его в дерево. Страница всегда содержит целые ветки. Ответы заблокированных аккаунтов исключены.

Параметры

Имя	Тип	Значение
`id`в пути	`string`обязательно	`id` поста.
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.
`cursor`в query	`string`необязательно	`next` из предыдущего ответа. Без него — с начала.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies?limit=20"

Ответ

Отвечает страницей Reply в виде `items` и `next`.

Пример

{
  "items": [
    {
      "id": "9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a",
      "text": "Same here, the lavender is full of them.",
      "kind": "post",
      "author": {
        "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
        "handle": "jon",
        "name": "Jon",
        "verified": false,
        "accountKind": "person"
      },
      "community": null,
      "media": [],
      "poll": null,
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 0,
        "likes": 3,
        "reposts": 0
      },
      "pinned": false,
      "createdAt": 1758624600000,
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "parentId": null
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Возможные статусы: 200304400401404429

POST`/api/v2/posts/{id}/replies`

Ответить на пост.

Право write
с v2.0

В медленном режиме — один ответ на человека раз в 10 минут, иначе 429. Автор и аккаунты, на которые он подписан, освобождены.

Параметры

Имя	Тип	Значение
`id`в пути	`string`обязательно	`id` поста.
`text`в теле	`string`обязательно	Текст поста, ответа или сообщения.
`parentId`в теле	`string`необязательно	`id` ответа, на который отвечает этот. Без него — прямо к посту.

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

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Same here, the lavender is full of them."}' \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies"

Ответ

Отвечает одним Created.

Пример

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

Возможные статусы: 200400401403404429

Опросы

Опрос — это пост, у которого задан poll. У голосования свой путь.

POST`/api/v2/posts/{id}/vote`

Принять участие в опросе.

Право write
с v2.0

Голоса по вариантам равны null, пока ты не проголосовал или опрос не закончился. total есть всегда.

Параметры

Имя	Тип	Значение
`id`в пути	`string`обязательно	`id` поста.
`option`в теле	`integer`обязательно	Какой вариант, считая с 0. При множественном выборе вызывай по разу на вариант.
`retract`в теле	`boolean`необязательно	`true` отзывает голос.

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

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"option":0}' \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/vote"

Ответ

Отвечает одним Ok.

Пример

{
  "ok": true
}

Возможные статусы: 200400401403404429

Профили

Публичные профили по короткому имени и то, что они опубликовали.

GET`/api/v2/profiles/{handle}`

Профиль по его короткому имени.

Право read
с ETag
с v2.0

Параметры

Имя	Тип	Значение
`handle`в пути	`string`обязательно	Короткое имя профиля.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/profiles/mara"

Ответ

Отвечает одним Profile.

Пример

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

Возможные статусы: 200304400401404429

GET`/api/v2/profiles/{handle}/posts`

Публичные посты одного профиля, сначала новые.

Право read
с пагинацией
с ETag
с v2.0

На публичных путях counts.likes и counts.reposts всегда 0, а pinned — false.

Посты в группах находятся не здесь, а в /communities/{id}/posts.

Параметры

Имя	Тип	Значение
`handle`в пути	`string`обязательно	Короткое имя профиля.
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.
`cursor`в query	`string`необязательно	`next` из предыдущего ответа. Без него — с начала.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/profiles/mara/posts?limit=20"

Ответ

Отвечает страницей Post в виде `items` и `next`.

Пример

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Возможные статусы: 200304400401404429

Группы

Открытые группы и их посты.

GET`/api/v2/communities`

Открытые группы этого сервера.

Право read
с ETag
с v2.0

Отсортированы по числу участников и без пагинации; next всегда null.

Параметры

Имя	Тип	Значение
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/communities?limit=20"

Ответ

Отвечает страницей Community в виде `items` и `next`.

Пример

{
  "items": [
    {
      "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
      "name": "Urban Gardening",
      "description": "Balconies, allotments, rooftops: whatever grows.",
      "tags": [
        "garden",
        "bees"
      ],
      "members": 312,
      "joinPolicy": "open",
      "visibility": "open"
    }
  ],
  "next": null
}

Возможные статусы: 200304401429

GET`/api/v2/communities/{id}`

Одна группа по её id.

Право read
с ETag
с v2.0

Параметры

Имя	Тип	Значение
`id`в пути	`string`обязательно	`id` группы.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"

Ответ

Отвечает одним Community.

Пример

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening",
  "description": "Balconies, allotments, rooftops: whatever grows.",
  "tags": [
    "garden",
    "bees"
  ],
  "members": 312,
  "joinPolicy": "open",
  "visibility": "open"
}

Возможные статусы: 200304400401404429

GET`/api/v2/communities/{id}/posts`

Публичные посты одной группы, сначала новые.

Право read
с пагинацией
с ETag
с v2.0

На публичных путях counts.likes и counts.reposts всегда 0, а pinned — false.

Параметры

Имя	Тип	Значение
`id`в пути	`string`обязательно	`id` группы.
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.
`cursor`в query	`string`необязательно	`next` из предыдущего ответа. Без него — с начала.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/posts?limit=20"

Ответ

Отвечает страницей Post в виде `items` и `next`.

Пример

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Возможные статусы: 200304400401404429

Обзор

Тренды, поиск и собственные эмодзи сервера.

GET`/api/v2/tags`

Теги, которые сейчас в ходу.

Право read
с ETag
с v2.0

Не больше 10 популярных тегов по весу: каждое использование даёт 1 и вдвое уменьшается каждые 3 дня, один аккаунт даёт не больше 3 в день. posts — округлённый вес. limit только укорачивает список. Теги, выделенные командой, могут стоять выше.

Параметры

Имя	Тип	Значение
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/tags?limit=10"

Ответ

Отвечает страницей Tag в виде `items` и `next`.

Пример

{
  "items": [
    {
      "tag": "garden",
      "posts": 58
    }
  ],
  "next": null
}

Возможные статусы: 200304401429

GET`/api/v2/search`

Поиск по постам, именам, коротким именам и тегам.

Право read
с ETag
с v2.0

Ищет только публичное: посты вне групп, профили и теги. limit действует для каждого вида.

Параметры

Имя	Тип	Значение
`q`в query	`string`обязательно	Искомые слова.
`type`в query	`string`необязательно	Какой вид результатов. Без него — все виды.`allpostsprofilestags`
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/search?q=garden&type=posts"

Ответ

Отвечает одним SearchResult.

Пример

{
  "posts": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

Возможные статусы: 200304400401429

GET`/api/v2/emojis`

Собственные эмодзи сервера с адресами их картинок.

Право read
с ETag
с v2.1

В текстах эмодзи выглядит как :name:. Замени его картинкой из этого списка; неизвестные имена остаются текстом.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/emojis"

Ответ

Отвечает страницей Emoji в виде `items` и `next`.

Пример

{
  "items": [
    {
      "name": "tellmelo",
      "url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
    }
  ],
  "next": null
}

Возможные статусы: 200304401429

Твой аккаунт

Твой профиль и твоя лента.

GET`/api/v2/me`

Твой собственный профиль с id, который ждут остальные пути.

Право read
с ETag
с v2.0

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/me"

Ответ

Отвечает одним Profile.

Пример

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

Возможные статусы: 200304401429

GET`/api/v2/feed`

Твоя собственная лента в том виде, как её собирает приложение.

Право read
с пагинацией
с v2.0

Без ETag, потому что порядок всё время меняется. Начатый список остаётся неизменным до конца.

Параметры

Имя	Тип	Значение
`tab`в query	`string`необязательно	Какая лента: `for-you`, `following`, `latest` или `bookmarks`. По умолчанию `latest`.`for-youfollowinglatestbookmarks`
`tag`в query	`string`необязательно	Только посты об этом теге: написанные с ним или распознанные сервером. Без него — без фильтра.
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.
`cursor`в query	`string`необязательно	`next` из предыдущего ответа. Без него — с начала.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/feed?tab=following&limit=20"

Ответ

Отвечает страницей Post в виде `items` и `next`.

Пример

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Возможные статусы: 200400401429

Уведомления

Что происходило вокруг твоего аккаунта, страница за страницей.

GET`/api/v2/notifications`

Твои уведомления, сначала новые.

Право read
с пагинацией
с ETag
с v2.0

Чтение ничего не отмечает прочитанным; это делает POST /notifications/read. События одного вида на одном посте делят строку; more говорит, сколько их.

Параметры

Имя	Тип	Значение
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.
`cursor`в query	`string`необязательно	`next` из предыдущего ответа. Без него — с начала.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/notifications?limit=20"

Ответ

Отвечает страницей Notification в виде `items` и `next`.

Пример

{
  "items": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "kind": "like",
      "text": null,
      "actor": {
        "handle": "jon",
        "name": "Jon"
      },
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "read": false,
      "more": 2,
      "createdAt": 1758624300000,
      "updatedAt": 1758624900000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Возможные статусы: 200304401429

POST`/api/v2/notifications/read`

Отметить уведомления прочитанными.

Право write
с v2.0

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

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/notifications/read"

Ответ

Отвечает одним Ok.

Пример

{
  "ok": true
}

Возможные статусы: 200401403429

Сообщения

Твой ящик и переписки. Переписка называется по другому аккаунту.

GET`/api/v2/conversations`

Твой ящик: по строке на переписку, сначала самая свежая.

Право read
с пагинацией
с ETag
с v2.0

Параметры

Имя	Тип	Значение
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.
`cursor`в query	`string`необязательно	`next` из предыдущего ответа. Без него — с начала.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/conversations?limit=20"

Ответ

Отвечает страницей Conversation в виде `items` и `next`.

Пример

{
  "items": [
    {
      "with": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
      "handle": "jon",
      "name": "Jon",
      "excerpt": "See you on Saturday at the market!",
      "truncated": false,
      "fromMe": true,
      "lastMessageId": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
      "unread": 0,
      "updatedAt": 1758624060000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Возможные статусы: 200304401429

GET`/api/v2/conversations/{with}/messages`

Сообщения одной переписки, сначала новые.

Право read
с пагинацией
с ETag
с v2.0

Чтение ничего не отмечает прочитанным; это делает POST /conversations/{with}/read.

Параметры

Имя	Тип	Значение
`with`в пути	`string`обязательно	`id` другого аккаунта. У переписки нет собственного `id`.
`limit`в query	`integer`необязательно	Записей на страницу: по умолчанию 20, максимум 50.
`cursor`в query	`string`необязательно	`next` из предыдущего ответа. Без него — с начала.

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

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages?limit=20"

Ответ

Отвечает страницей Message в виде `items` и `next`.

Пример

{
  "items": [
    {
      "id": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
      "text": "See you on Saturday at the market!",
      "from": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "to": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
      "read": true,
      "media": [],
      "replyTo": null,
      "createdAt": 1758624060000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Возможные статусы: 200304400401404429

POST`/api/v2/conversations/{with}/messages`

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

Право write
с v2.0

Действуют правила приложения: кто тебя заблокировал, тому не написать, и учитываются настройки собеседника.

Прикреплять изображения через API пока нельзя, только в приложении.

Параметры

Имя	Тип	Значение
`with`в пути	`string`обязательно	`id` другого аккаунта. У переписки нет собственного `id`.
`text`в теле	`string`обязательно	Текст поста, ответа или сообщения.
`replyTo`в теле	`string`необязательно	`id` более раннего сообщения этой переписки, на которое отвечает это. С 2.2.

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

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"See you on Saturday at the market!"}' \
  "https://tellmelo.com/api/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages"

Ответ

Отвечает одним Ok.

Пример

{
  "ok": true
}

Возможные статусы: 200400401403404429

POST`/api/v2/conversations/{with}/read`

Отметить все сообщения переписки прочитанными.

Право write
с v2.1

Параметры

Имя	Тип	Значение
`with`в пути	`string`обязательно	`id` другого аккаунта. У переписки нет собственного `id`.

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

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/read"

Ответ

Отвечает одним Ok.

Пример

{
  "ok": true
}

Возможные статусы: 200400401403404429

Связи

Отметить, сохранить, репостнуть, подписаться, вступить, заблокировать: один путь, ставится и снимается через active.

POST`/api/v2/relations`

Отметить, сохранить, репостнуть, подписаться, вступить, заблокировать, скрыть — в зависимости от kind.

Право write
с v2.0

target — пост для like, save и repost, группа для join, аккаунт для follow, block и mute. active: false снимает связь.

Параметры

Имя	Тип	Значение
`kind`в теле	`string`обязательно	Какая связь: `like`, `save`, `repost`, `follow`, `join`, `block` или `mute` (с 2.2).`likesaverepostfollowjoinblockmute`
`target`в теле	`string`обязательно	`id` поста, профиля или группы, в зависимости от `kind`.
`active`в теле	`boolean`необязательно	`true` устанавливает связь, `false` снимает её.

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

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"like","target":"5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1","active":true}' \
  "https://tellmelo.com/api/v2/relations"

Ответ

Отвечает одним Ok.

Пример

{
  "ok": true
}

Возможные статусы: 200400401403429

Объекты

Все объекты, поле за полем. [] означает список.

`Service`

Ответ корня: кто отвечает и что может этот ключ.

Поле	Тип	Значение
`name`	`string`	Всегда `tellmelo`.
`version`	`string`	Версия API, например `2.1`.
`scope`	`string`	Что может этот ключ: `read` или `read write`.
`rateLimit`	`RateLimit`	Бюджет этого ключа.
`docs`	`string`	Где эта документация, в виде пути на этом сервере.
`spec`	`string`	Где машиночитаемое описание.

Пример

{
  "name": "tellmelo",
  "version": "2.10",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/legal/api",
  "spec": "/api/v2/openapi.json"
}

`RateLimit`

Бюджет этого ключа в текущей минуте.

Поле	Тип	Значение
`limit`	`integer`	Запросов в минуту.
`remaining`	`integer`	Сколько осталось в этой минуте.

Пример

{
  "limit": 120,
  "remaining": 117
}

`Post`

Пост, везде в одной и той же форме.

Поле	Тип	Значение
`id`	`string`	id поста.
`text`	`string`или null	Текст как написан (`null` для поста, который только опрос или только картинки).
`kind`	`string`	Что это за пост. `post` — Пост с текстом, картинками или цитатой. `poll` — Пост с опросом.
`author`	`ProfileBrief`	Кто его написал.
`community`	`CommunityBrief`или null	Группа, в которой он написан (`null` вне групп).
`media`	`Media[]`	Его изображения по порядку; пусто, если их нет.
`poll`	`Poll`или null	Опрос (`null`, если его нет).
`quotes`	`string`или null	id поста, который цитирует этот.
`continues`	`string`или null	id поста, который продолжает этот как дополнение.
`counts`	`Counts`	Ответы, отметки и репосты.
`pinned`	`boolean`	Закреплён ли он наверху профиля автора.
`createdAt`	`integer`	Когда он написан.

Пример

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "text": "The bees are back in the garden 🐝 #garden",
  "kind": "poll",
  "author": {
    "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
    "handle": "mara",
    "name": "Mara 🌻",
    "verified": true,
    "accountKind": "person"
  },
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening"
  },
  "media": [
    {
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "image",
      "poster": null
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": 1758710400000,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "createdAt": 1758624000000
}

`Reply`

Ответ под постом: пост с двумя дополнительными полями.

Все поля Post, а также:

Поле	Тип	Значение
`postId`	`string`	Пост, к которому относится вся ветка.
`parentId`	`string`или null	Ответ, на который отвечает этот (`null`, если отвечает прямо на пост).

Пример

{
  "id": "9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a",
  "text": "Same here, the lavender is full of them.",
  "kind": "post",
  "author": {
    "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
    "handle": "jon",
    "name": "Jon",
    "verified": false,
    "accountKind": "person"
  },
  "community": null,
  "media": [],
  "poll": null,
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 0,
    "likes": 3,
    "reposts": 0
  },
  "pinned": false,
  "createdAt": 1758624600000,
  "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "parentId": null
}

`Counts`

Сколько у поста ответов, отметок и репостов.

Поле	Тип	Значение
`replies`	`integer`	Ответы, все уровни вместе.
`likes`	`integer`	Отметки «нравится».
`reposts`	`integer`	Репосты.

Пример

{
  "replies": 4,
  "likes": 31,
  "reposts": 2
}

`Media`

Изображение поста или сообщения.

Поле	Тип	Значение
`url`	`string`	Адрес картинки или видео относительно этого сервера. Загружай с ключом в заголовке.
`kind`	`string`	`image`, `video` или `gif` (с 2.10). Видео и GIF — это файлы MP4. `image` — Изображение (WebP или JPEG). `video` — Видео в MP4 со звуком. `gif` — GIF в виде беззвучного зацикленного MP4.
`poster`	`string`или null	Для видео и GIF адрес картинки предпросмотра, иначе `null` (с 2.10).

Пример

{
  "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
  "kind": "image",
  "poster": null
}

`Poll`

Опрос поста.

Поле	Тип	Значение
`options`	`PollOption[]`	Варианты по порядку. `option` при голосовании считается с 0.
`total`	`integer`	Все голоса вместе, всегда есть.
`multiple`	`boolean`	Можно ли выбрать больше одного варианта.
`endsAt`	`integer`или null	Когда опрос заканчивается (`null`, если он без конца).
`running`	`boolean`	Можно ли ещё голосовать.
`resultsVisible`	`boolean`	Показываются ли голоса по вариантам (см. `votes`).
`myVotes`	`integer[]`	Выбранные тобой варианты, считая с 0.

Пример

{
  "options": [
    {
      "text": "Lavender",
      "votes": 12
    },
    {
      "text": "Sunflowers",
      "votes": 7
    },
    {
      "text": "Clover",
      "votes": 3
    }
  ],
  "total": 22,
  "multiple": false,
  "endsAt": 1758710400000,
  "running": true,
  "resultsVisible": true,
  "myVotes": [
    0
  ]
}

`PollOption`

Один вариант ответа опроса.

Поле	Тип	Значение
`text`	`string`	Вариант ответа.
`votes`	`integer`или null	Его голоса (`null`, пока результаты скрыты).

Пример

{
  "text": "Lavender",
  "votes": 12
}

`ProfileBrief`

Профиль, как он появляется внутри других объектов: как автор, в поиске.

Поле	Тип	Значение
`id`	`string`	id аккаунта: то, что ждут `/relations` и `/conversations/{with}`.
`handle`	`string`	Короткое имя, без `@`.
`name`	`string`	Отображаемое имя. Может содержать эмодзи, в том числе `:name:`.
`verified`	`boolean`	Подтверждён ли аккаунт.
`accountKind`	`string`	Какого вида аккаунт. `person` — Человек. `business` — Компания. `association` — Клуб или объединение. `automated` — Автоматический аккаунт, например бот.

Пример

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person"
}

`Profile`

Профиль сам по себе, с описанием и подписчиками.

Все поля ProfileBrief, а также:

Поле	Тип	Значение
`about`	`string`или null	Описание (`null`, если его нет).
`website`	`string`или null	Сайт профиля (`null`, если его нет). С 2.3.
`websiteVerified`	`boolean`	Ссылается ли сайт на этот профиль через `rel=me`, проверяется еженедельно. С 2.3.
`followers`	`integer`	Сколько аккаунтов на него подписаны.
`createdAt`	`integer`или null	Когда создан аккаунт (`null`, пока участник скрывает дату регистрации; с 2.9).

Пример

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

`CommunityBrief`

Группа, в которой написан пост.

Поле	Тип	Значение
`id`	`string`	id группы.
`name`	`string`или null	Её название.

Пример

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening"
}

`Community`

Группа этого сервера.

Поле	Тип	Значение
`id`	`string`	id группы.
`name`	`string`	Её название.
`description`	`string`или null	Описание (`null`, если его нет).
`tags`	`string[]`	Темы, которым она посвящена.
`members`	`integer`	Сколько в ней участников.
`joinPolicy`	`string`	Как в неё попасть. `open` — Вступить может любой. `application` — Для вступления нужна заявка, которую принимает группа. `invite` — Только по приглашению.
`visibility`	`string`	Через ключ всегда `open`. `open` — Видна всем.

Пример

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening",
  "description": "Balconies, allotments, rooftops: whatever grows.",
  "tags": [
    "garden",
    "bees"
  ],
  "members": 312,
  "joinPolicy": "open",
  "visibility": "open"
}

`Tag`

Тег и сколько постов его несут.

Поле	Тип	Значение
`tag`	`string`	Тег, без `#`.
`posts`	`integer`	Сколько недавних постов его несут.

Пример

{
  "tag": "garden",
  "posts": 58
}

`SearchResult`

Три списка, возможно пустых.

Поле	Тип	Значение
`posts`	`Post[]`	Подходящие посты, сначала новые.
`profiles`	`ProfileBrief[]`	Подходящие профили, по короткому имени.
`tags`	`Tag[]`	Подходящие теги, сначала самые используемые.

Пример

{
  "posts": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

`Emoji`

Эмодзи этого сервера.

Поле	Тип	Значение
`name`	`string`	Имя, как оно стоит между двоеточиями.
`url`	`string`	Адрес картинки относительно этого сервера.

Пример

{
  "name": "tellmelo",
  "url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
}

`Notification`

Уведомление. Одна строка может объединять несколько событий одного вида.

Поле	Тип	Значение
`id`	`string`	id уведомления.
`kind`	`string`	Что произошло. `reply` — Кто-то тебе ответил. `like` — Кому-то нравится твой пост. `reply_like` — Кому-то нравится твой ответ. `repost` — Кто-то репостнул твой пост. `follow` — Кто-то на тебя подписался. `mention` — Кто-то тебя упомянул. `group_mention` — Кто-то упомянул группу, которую ты ведёшь; `text` — её название. `message` — Кто-то написал тебе сообщение. `scheduled` — Твой запланированный пост опубликован. `reminder` — Пора напоминания о сохранённом посте. `report` — Что стало с жалобой, которую ты отправил. `moderation` — Решение по твоему аккаунту: предупреждение, ограничение, обжалование. `team` — Новая работа для команды (только владельцы, админы и модераторы). `reward` — Награда за приглашение скоро истечёт или истекла. `gift` — Подарок от команды: тариф или искры для тебя или для группы, которую ты ведёшь. `present` — Подарок от участника: искры или время тарифа; участник — это `actor`. `spark` — Искры скоро закончатся, или группа, которую ты ведёшь, достигла уровня или удерживает его лишь на время. `loyalty` — О ритме верности: активная неделя засчитана или не хватает одного дня, награда новая или скоро пропадёт. `impact` — Как прошли твои посты за двенадцать часов через сутки, в одном уведомлении. `discovery` — Приглашение в программу «Находка» или сообщение о начале или конце места в ней. `group_post` — Новый пост в группе, колокольчик которой на это настроен. `group_moderation` — Руководство группы удалило твой пост или тебя из группы.
`text`	`string`или null	Только для жалоб и модерации: связанный текст, иначе `null`.
`actor`	`Actor`	Кто это сделал.
`postId`	`string`или null	Пост, о котором речь (`null`, если ни о каком).
`read`	`boolean`	Отмечено ли прочитанным.
`more`	`integer`	Сколько ещё событий представляет эта строка, кроме названного.
`createdAt`	`integer`	Когда это произошло впервые.
`updatedAt`	`integer`	Когда к нему в последний раз добавилось событие. Список отсортирован по этому полю.

Пример

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "kind": "like",
  "text": null,
  "actor": {
    "handle": "jon",
    "name": "Jon"
  },
  "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "read": false,
  "more": 2,
  "createdAt": 1758624300000,
  "updatedAt": 1758624900000
}

`Actor`

Кто вызвал уведомление.

Поле	Тип	Значение
`handle`	`string`	Короткое имя.
`name`	`string`	Отображаемое имя.

Пример

{
  "handle": "jon",
  "name": "Jon"
}

`Conversation`

Одна строка твоего ящика.

Поле	Тип	Значение
`with`	`string`	id другого аккаунта: то, что ждёт `/conversations/{with}/messages`.
`handle`	`string`	Его короткое имя.
`name`	`string`	Его отображаемое имя.
`excerpt`	`string`или null	Начало последнего сообщения (`null`, если в нём нет текста).
`truncated`	`boolean`	Обрезан ли отрывок.
`fromMe`	`boolean`	Твоё ли последнее сообщение.
`lastMessageId`	`string`	id последнего сообщения.
`unread`	`integer`	Сколько его сообщений ты ещё не прочитал.
`updatedAt`	`integer`	Когда написано последнее сообщение.

Пример

{
  "with": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "handle": "jon",
  "name": "Jon",
  "excerpt": "See you on Saturday at the market!",
  "truncated": false,
  "fromMe": true,
  "lastMessageId": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
  "unread": 0,
  "updatedAt": 1758624060000
}

`Message`

Сообщение в переписке.

Поле	Тип	Значение
`id`	`string`	id сообщения.
`text`	`string`или null	Текст (`null` для сообщения только из картинок).
`from`	`string`	id аккаунта, который его написал.
`to`	`string`	id аккаунта, которому оно написано.
`read`	`boolean`	Прочитал ли его получатель.
`media`	`Media[]`	Его изображения; пусто, если их нет.
`replyTo`	`string`или null	`id` сообщения, на которое отвечает это (`null`, если ни на какое). С 2.2.
`createdAt`	`integer`	Когда отправлено.

Пример

{
  "id": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
  "text": "See you on Saturday at the market!",
  "from": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "to": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "read": true,
  "media": [],
  "replyTo": null,
  "createdAt": 1758624060000
}

`Created`

Ответ записи, которая что-то создала.

Поле	Тип	Значение
`id`	`string`	id созданного.
`scheduledFor`	`integer`или null	Когда оно появится, если публикация запланирована (иначе `null`).
`deleteAt`	`integer`или null	Когда оно само удалится, если это задано (иначе `null`).

Пример

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

`Ok`

Ответ записи, которой нечего вернуть.

Поле	Тип	Значение
`ok`	`boolean`	Всегда `true`.

Пример

{
  "ok": true
}

Машиночитаемое описание

Таблица, на которой построена эта страница, доступна как OpenAPI по адресу /api/v2/openapi.json.

https://tellmelo.com/api/v2/openapi.json

Чего мы ждём

Действуют те же правила, что и везде: никакой травли, никакого спама, никакого контента, на который у тебя нет прав. За то, что публикует твой ключ, отвечаешь ты.

API

Обзор

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

Попробовать

Твой ключ

Что может ключ

Чего не может ни один ключ

Запросы и ответы

Страницы

Только новое

Лимиты

Заголовки

Что ты отправляешь

Что приходит в ответ

Когда что-то не работает

Версии

Конечные точки

Вход

GET/api/v2

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

Ответ

Посты

GET/api/v2/posts

Параметры

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

Ответ

GET/api/v2/posts/{id}

Параметры

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

Ответ

POST/api/v2/posts

Параметры

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

Ответ

DELETE/api/v2/posts/{id}

Параметры

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

Ответ

Ответы

GET/api/v2/posts/{id}/replies

Параметры

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

Ответ

POST/api/v2/posts/{id}/replies

Параметры

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

Ответ

Опросы

POST/api/v2/posts/{id}/vote

Параметры

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

Ответ

Профили

GET/api/v2/profiles/{handle}

Параметры

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

Ответ

GET/api/v2/profiles/{handle}/posts

Параметры

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

Ответ

Группы

GET/api/v2/communities

Параметры

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

Ответ

GET/api/v2/communities/{id}

Параметры

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

Ответ

GET/api/v2/communities/{id}/posts

Параметры

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

Ответ

Обзор

GET/api/v2/tags

Параметры

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

Ответ

GET/api/v2/search

GET`/api/v2`

GET`/api/v2/posts`

GET`/api/v2/posts/{id}`

POST`/api/v2/posts`

DELETE`/api/v2/posts/{id}`

GET`/api/v2/posts/{id}/replies`

POST`/api/v2/posts/{id}/replies`

POST`/api/v2/posts/{id}/vote`

GET`/api/v2/profiles/{handle}`

GET`/api/v2/profiles/{handle}/posts`

GET`/api/v2/communities`

GET`/api/v2/communities/{id}`

GET`/api/v2/communities/{id}/posts`

GET`/api/v2/tags`

GET`/api/v2/search`

GET`/api/v2/emojis`

GET`/api/v2/me`

GET`/api/v2/feed`

GET`/api/v2/notifications`

POST`/api/v2/notifications/read`

GET`/api/v2/conversations`

GET`/api/v2/conversations/{with}/messages`

POST`/api/v2/conversations/{with}/messages`

POST`/api/v2/conversations/{with}/read`

POST`/api/v2/relations`

`Service`

`RateLimit`

`Post`

`Reply`

`Counts`

`Media`

`Poll`

`PollOption`

`ProfileBrief`

`Profile`

`CommunityBrief`

`Community`

`Tag`

`SearchResult`

`Emoji`

`Notification`

`Actor`

`Conversation`

`Message`

`Created`

`Ok`