Contents I want to … Choose what you have in mind; below are only the steps for it. The full reference follows further down.
Create the bot in one of your groups, in the group menu under “Bots → My bots”, with a picture, name and @name. You only see its token once. Share its “Add bot” link or submit it for the bot directory, where it appears once the team has checked it; anyone who may manage roles in a group takes it in with the permissions they agree to. Receive what happens in its groups as a stream (GET /v2/events/stream) or at your address, and write with POST /v2/channels/{id}/messages. More under Bots . Register commands (PUT /v2/me/commands) and answer with cards and buttons; a bot plays music with a seat in a voice channel (POST /v2/channels/{id}/voice). Overview v2 lets your own programs talk to tellmelo: one key per request, JSON back, every list pages the same way. The same rules apply as in the app.
Every path begins with https://api.tellmelo.com/v2. Requests and answers are JSON in UTF-8. Field names, codes and values are English and stay English. A key acts as your account: what you can’t see in the app, it can’t read either. https://api.tellmelo.com/v2Quick start Create a key under “Developer area → API” and copy it. It is shown only once. Call the root with it. The answer shows the version, the key’s rights and the requests left this minute. Every path works the same way: key in the header, JSON back, items and next for lists. curl -H "Authorization: Bearer tm_key_…" https://api.tellmelo.com/v2{
"name": "tellmelo",
"version": "2.20",
"scope": "read write",
"rateLimit": {
"limit": 120,
"remaining": 117
},
"docs": "/developers/docs",
"spec": "/api/v2/openapi.json"
}Next: /me for your profile, /posts for public posts, /feed for your feed.
Try it Pick a task, fill in the fields and copy the request or send it from here. Writing asks first. The code reads the key from TELLMELO_KEY.
Task GET / GET /posts GET /posts/{id} POST /posts DELETE /posts/{id} GET /me/scheduled POST /posts/{id}/schedule POST /posts/{id}/edit GET /posts/{id}/reply-settings PUT /posts/{id}/reply-settings POST /posts/{id}/coauthor DELETE /posts/{id}/coauthor POST /posts/{id}/pin GET /posts/{id}/replies POST /posts/{id}/replies POST /replies/{id}/edit DELETE /replies/{id} POST /replies/{id}/like POST /replies/{id}/vote POST /replies/{id}/pick GET /posts/{id}/replies/waiting POST /replies/{id}/decide GET /posts/{id}/replies/planned PUT /me/planned-replies/{id} POST /me/planned-replies/{id}/send DELETE /me/planned-replies/{id} POST /posts/{id}/vote GET /profiles/{handle} GET /profiles/{handle}/posts GET /profiles/{handle}/events POST /me/events PUT /me/events/{id} DELETE /me/events/{id} GET /me/events/{id}/signups POST /events/{id}/signup GET /communities GET /communities/{id} GET /communities/{id}/posts GET /communities/{id}/members GET /communities/{id}/roles GET /communities/{id}/bell GET /invites/{code} PUT /roles/{id}/self GET /communities/{id}/emojis PUT /communities/{id}/bell POST /invites/{code}/join GET /communities/{id}/bots GET /communities/{id}/channels GET /channels/{id}/messages POST /channels/{id}/messages POST /channels/{id}/read DELETE /channel-messages/{id} GET /communities/{id}/voice POST /communities/{id}/emojis DELETE /communities/{id}/emojis/{name} POST /communities/{id}/roles PUT /roles/{id} DELETE /roles/{id} PUT /communities/{id}/roles/order PUT /roles/{id}/members/{member} POST /communities/{id}/channels PUT /channels/{id} DELETE /channels/{id} PUT /communities/{id}/channels/order PUT /communities/{id}/channels/shape GET /channels/{id}/overrides PUT /channels/{id}/overrides/{role} POST /communities/{id}/categories PUT /categories/{id} DELETE /categories/{id} PUT /communities/{id}/feed GET /communities/{id}/invites POST /communities/{id}/invites DELETE /invites/{code} POST /channel-messages/{id}/remove POST /communities/{id}/posts/{post}/remove DELETE /communities/{id}/members/{member} PUT /communities/{id}/members/{member}/timeout DELETE /communities/{id}/members/{member}/timeout GET /communities/{id}/bans PUT /communities/{id}/bans/{member} DELETE /communities/{id}/bans/{member} GET /communities/{id}/log POST /communities PUT /communities/{id} GET /events GET /events/stream GET /me/commands PUT /me/commands POST /interactions/{id}/reply POST /channels/{id}/voice GET /tags GET /search GET /emojis GET /media GET /media/mine GET /media/{id} POST /media/uploads POST /media/{id} DELETE /media/{id} GET /me GET /feed POST /me/pictures PUT /me/profile GET /me/emojis POST /me/emojis/pictures POST /me/emojis DELETE /me/emojis/{name} PUT /me/emojis/sharing GET /me/webhooks POST /me/webhooks DELETE /me/webhooks/{id} POST /me/webhooks/{id}/test GET /notifications POST /notifications/read GET /conversations GET /conversations/{with}/messages POST /conversations/{with}/messages POST /conversations/{with}/read DELETE /conversations/{with}/messages/{id} POST /conversations/{with}/planned GET /me/planned-messages POST /me/planned-messages/{id}/send DELETE /me/planned-messages/{id} POST /relations GET /profiles/{handle}/followers GET /profiles/{handle}/following GET /me/relations GET /me/collections POST /me/collections PUT /me/collections/{id} DELETE /me/collections/{id} GET /me/collections/{id}/posts POST /me/collections/{id}/posts GET /partner/quota GET /partner/gifts POST /partner/gifts GET /gift-drops POST /gift-drops read API version and name of this instance.
curl \
-H "Authorization: Bearer $TELLMELO_KEY" \
"https://api.tellmelo.com/v2"Your key Up to 10 keys per account, each with a name, its own permissions and, if you like, an expiry date. A key begins with tm_key_ and is shown only once. Lost it? Renew it; the old value stops working.
You create it under “Developer area → API”. It travels in the header of the request:
curl -H "Authorization: Bearer tm_key_…" \
https://api.tellmelo.com/v2/postsOr, if that is more convenient, in a header of its own:
curl -H "X-Tellmelo-Key: tm_key_…" https://api.tellmelo.com/v2Not in the URL: it would end up in logs and browser history.
The same key loads images: every url points to /api/media; send the key in the header there too.
curl -H "Authorization: Bearer tm_key_…" \
-o picture.webp "https://api.tellmelo.com/media?id=…"What a key may do A key can always read and, if you allow it, also write, give gifts, upload media and run groups. Each path below says what it needs:
read : reading. Public posts, profiles, groups and tags, plus your feed, notifications, messages and the channels of your groups.write : acting. Posting, replying, voting, sending messages, writing in a group chat, following, joining, blocking, marking notifications as read.gifts : giving. From a partner’s quota to a member, and gifts under a new post. A separate permission, so a key meant for posting can never give anything away.media : your own media library. Uploading, changing, sharing and removing GIFs and videos. A separate permission, because uploads cost the account’s video points. Finding shared GIFs and videos only needs read .groups : running groups. Roles, channels, categories, invitation links, the feed channel, removals, timeouts, kicks and bans, as far as your account may in the group. A permission of its own, so a key for posting never changes who may do what in a group.What no key can do No key reaches password, email address, account type, place, role, deletion, sessions, push devices or other keys, nor the admin area or group leadership. What the password protects, no key can do.
Bots A bot is an account of its own, of the kind bot, for groups: without a password or email address, run by your program with its own key. It uses the same API as every account and can do in groups whatever its role there allows.
In one of your groups, open the group menu, go to “Bots → My bots” and create a bot with a picture, banner, name, username and description. The token is shown only once; it has the permissions read, write, media and groups. Pass on the bot's link, or submit it for the bot directory; it appears there once the team has checked it. Anyone who may manage roles in a group chooses the permissions; the bot joins and gets a role of its own. Your program sends the token as Authorization: Bearer …, reads the events of its groups as a stream and works with the routes under Bots , Channels and Groups . A small bot that reads the events as a stream and answers the command /ping with pong, only for whoever asked:
// Node 18 or newer: reads the events of the bot's groups as they happen and answers /ping.
const BASE = 'https://api.tellmelo.com/v2';
const KEY = process.env.TELLMELO_BOT_TOKEN;
const call = (method, path, body) =>
fetch(BASE + path, {
method,
headers: { Authorization: 'Bearer ' + KEY, 'Content-Type': 'application/json' },
body: body && JSON.stringify(body),
}).then((r) => r.json());
await call('PUT', '/me/commands', { commands: [{ name: 'ping', description: 'Answers pong' }] });
let last = '';
for (;;) {
// The stream closes after ten minutes; Last-Event-ID goes on where it stopped.
const res = await fetch(BASE + '/events/stream', {
headers: { Authorization: 'Bearer ' + KEY, ...(last && { 'Last-Event-ID': last }) },
});
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = '';
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffer += value;
let end;
while ((end = buffer.indexOf('
')) >= 0) {
const data = buffer.slice(0, end).split('
').find((l) => l.startsWith('data: '));
buffer = buffer.slice(end + 2);
if (!data) continue;
const event = JSON.parse(data.slice(6));
last = event.id;
if (event.type === 'command' && event.data.command === 'ping')
await call('POST', '/interactions/' + event.data.interaction + '/reply', { text: 'pong', private: true });
}
}
}The same bot in Python, fetching the events page by page:
# Python 3 with requests: the same bot, reading the events page by page.
import os, time, requests
BASE = 'https://api.tellmelo.com/v2'
H = {'Authorization': 'Bearer ' + os.environ['TELLMELO_BOT_TOKEN']}
requests.put(BASE + '/me/commands', headers=H,
json={'commands': [{'name': 'ping', 'description': 'Answers pong'}]})
since = '0'
while True:
page = requests.get(BASE + '/events', headers=H, params={'since': since}).json()
for event in page['items']:
if event['type'] == 'command' and event['data']['command'] == 'ping':
requests.post(f"{BASE}/interactions/{event['data']['interaction']}/reply",
headers=H, json={'text': 'pong'})
since = page['next'] or since
time.sleep(2)What a bot may do in a group is decided by its role there, not by the token. The role carries its name; the group changes its permissions under the roles in the group settings and removes the bot in the group menu under “Bots → In this group”. Up to 5 bots per account; per group as many as its perks allow. A bot writes at most 30 messages a minute per group, can't be found through search and only writes to people who wrote to it first. The limits apply. Events also arrive at an HTTPS address of your own (signed like the webhooks, with retries). On top: commands (PUT /v2/me/commands) with answers for everyone or only whoever asked, cards and buttons in messages, and music in voice channels (POST /v2/channels/{id}/voice): all under Bots . Pages Every list takes limit and cursor and answers with items and next. Send next back as cursor to get the next page; when next is empty, you are done. The cursor is opaque: don’t parse it, don’t build one.
{ "items": [ … ], "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx" }
curl -H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts?limit=20&cursor=MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"Without limit, 20 entries, at most 50. Some lists don’t page; their next is always null.
Only what is new Every answer carries an ETag. Send it back as If-None-Match next time: if nothing changed, you get 304 with no body.
ETag: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc"
If-None-Match: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc" → 304Exceptions: /feed has no ETag because its order keeps changing, and writes never answer 304.
Limits A key may make 120 requests per minute, 600 with the “Organisation” plan, unless the team sets otherwise. Above that you get 429 and nothing was carried out. Wait a minute and send the request again.
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1758624060Writes also count against the app’s limits, such as how many posts in a few minutes. That too answers 429 with rate_limited.
When something does not work Errors come as JSON: a fixed English code in error for your program and a sentence in message for people, plus the matching status code. Compare only the code; the sentence may change.
{ "error": "rate_limited",
"message": "Too many requests. Try again in a minute.",
"limit": 120 }Some errors bring one more field: docs with a 401 for a missing key, limit with a 429.
Status Code Meaning 400bad_requestThe request can’t be read, a required field is missing, or a value isn’t allowed. 401key_missingNo key in the header. 401key_invalidThe key isn’t valid: mistyped, replaced, or the account is banned. 401unauthorizedRejected as not signed in, for a reason other than the key. 403scope_missingThe key lacks the required right, usually write. 403account_data_lockedAccount data such as password, email address or deletion is off limits to keys. 403forbiddenYour account may not do this, for example because of a revoked right or a block. 403timed_outA timeout mutes your account in this group right now. 404unknown_pathThere is no such path, or not with this method. 404not_foundNot found, or you may not see it. 409conflictIt collides with what is already there, for example a name that is taken. 409feed_offThis group’s feed channel is off. 413too_largeToo large for this instance. 422unprocessableReadable, but not possible in this form. 429rate_limitedToo many requests. Nothing happened; wait and try again. 500internal_errorSomething went wrong on the server.
Versions The version is in the path. As long as it says v2, paths and fields stay the same; new things are only added.
Additions raise the second number. Every path says since when it exists.
https://api.tellmelo.com/v1/ is gone: the old paths answer 410 and name the new way in the body.
Endpoints All paths at a glance, then each one with an example.
Path Right What for The way in GET /v2readAPI version and name of this instance. Posts GET /v2/postsreadThe public posts, newest first. GET /v2/posts/{id}readA single post, by its id. POST /v2/postswritePublish a post. DELETE /v2/posts/{id}writeRemove one of your own posts. GET /v2/me/scheduledreadYour posts that aren’t out yet, and what they’re waiting for. POST /v2/posts/{id}/schedulewriteChange when a scheduled post goes out, or when a post deletes itself. POST /v2/posts/{id}/editwriteChange the text of one of your posts. GET /v2/posts/{id}/reply-settingsreadWho may reply to your own post, whether replies wait for approval, and slow mode. PUT /v2/posts/{id}/reply-settingswriteChange the reply settings of your own post. Whatever you leave out stays. POST /v2/posts/{id}/coauthorwriteAccept or decline an invitation to co-author a post. DELETE /v2/posts/{id}/coauthorwriteStep back as co-author, or as the author take the co-author off the post. POST /v2/posts/{id}/pinwritePin your own post to the top of your profile, or unpin it. Replies GET /v2/posts/{id}/repliesreadThe replies to a post, without blocked accounts. POST /v2/posts/{id}/replieswriteReply to a post. POST /v2/replies/{id}/editwriteChange the text of one of your replies. DELETE /v2/replies/{id}writeRemove one of your replies. POST /v2/replies/{id}/likewriteUpvote a reply (a like is an upvote since replies are voted up and down), or take the upvote back; a downvote stays. POST /v2/replies/{id}/votewriteVote a reply up or down, or take your vote back. Answers with your vote and the score after it. POST /v2/replies/{id}/pickwriteHighlight a reply under your own post as the best one, or take the highlight back. GET /v2/posts/{id}/replies/waitingreadThe replies waiting for approval under a post: all of them under your own post, otherwise only your own. POST /v2/replies/{id}/decidewriteApprove or decline a waiting reply under your own post. A declined reply is deleted. GET /v2/posts/{id}/replies/plannedreadYour own replies planned for later under a post. PUT /v2/me/planned-replies/{id}writeChange the text or time of a planned reply. A failed one waits again afterwards. POST /v2/me/planned-replies/{id}/sendwriteSend a planned reply right away. DELETE /v2/me/planned-replies/{id}writeDelete a planned reply. Polls POST /v2/posts/{id}/votewriteTake part in a poll. Profiles GET /v2/profiles/{handle}readA profile, by its short name. GET /v2/profiles/{handle}/postsreadThe public posts of one profile, newest first. GET /v2/profiles/{handle}/eventsreadThe upcoming events of a profile, soonest first. POST /v2/me/eventswriteCreate an event. Answers with its id. PUT /v2/me/events/{id}writeChange one of your events. All fields are set anew. DELETE /v2/me/events/{id}writeDelete one of your events. GET /v2/me/events/{id}/signupsreadWho signed up for one of your events. POST /v2/events/{id}/signupwriteSign up for an event or sign off. Groups GET /v2/communitiesreadThe open groups of this instance; with mine=true your account’s groups. GET /v2/communities/{id}readA single group, by its id. GET /v2/communities/{id}/postsreadThe posts of a group’s feed channel, newest first. GET /v2/communities/{id}/membersreadThe members of a group with their roles. GET /v2/communities/{id}/rolesreadThe roles of a group, the highest first, @everyone last. GET /v2/communities/{id}/bellreadWhich notifications a group sends you. GET /v2/invites/{code}readThe group behind an invitation link, before joining. PUT /v2/roles/{id}/selfwriteTake or put down a self-assignable role. GET /v2/communities/{id}/emojisreadA group's own emojis. PUT /v2/communities/{id}/bellwriteSet which notifications a group sends you. POST /v2/invites/{code}/joinwriteJoin a group with an invitation link. GET /v2/communities/{id}/botsreadThe bots of a group with what their role allows. Channels GET /v2/communities/{id}/channelsreadThe channels of a group you can see, in their order. GET /v2/channels/{id}/messagesreadThe messages of a chat channel, newest first. POST /v2/channels/{id}/messageswriteWrite a message in a chat channel. POST /v2/channels/{id}/readwriteMark a chat channel as read up to a point in time. DELETE /v2/channel-messages/{id}writeDelete one of your messages in a chat channel. GET /v2/communities/{id}/voicereadWho is in a group’s voice channels right now, per channel. Running groups POST /v2/communities/{id}/emojisgroupsGive the group an emoji. DELETE /v2/communities/{id}/emojis/{name}groupsRemove an emoji from the group. POST /v2/communities/{id}/rolesgroupsCreate a role. PUT /v2/roles/{id}groupsChange a role’s name, colour and permissions. DELETE /v2/roles/{id}groupsDelete a role. PUT /v2/communities/{id}/roles/ordergroupsSet the rank of the roles. PUT /v2/roles/{id}/members/{member}groupsGive a member a role or take it away. POST /v2/communities/{id}/channelsgroupsCreate a chat channel. PUT /v2/channels/{id}groupsChange a channel’s name, topic and category. DELETE /v2/channels/{id}groupsDelete a chat channel with its messages. PUT /v2/communities/{id}/channels/ordergroupsSet the order of the categories and chat channels. PUT /v2/communities/{id}/channels/shapegroupsSet the shape of all the group’s channel symbols. GET /v2/channels/{id}/overridesgroupsWhat roles may do differently in a channel than in the group. PUT /v2/channels/{id}/overrides/{role}groupsSet what a role may do differently in a channel. POST /v2/communities/{id}/categoriesgroupsCreate a category for channels. PUT /v2/categories/{id}groupsRename a category. DELETE /v2/categories/{id}groupsDelete a category. PUT /v2/communities/{id}/feedgroupsSwitch a group’s feed channel on or off. GET /v2/communities/{id}/invitesgroupsA group’s invitation links that still work. POST /v2/communities/{id}/invitesgroupsCreate an invitation link. DELETE /v2/invites/{code}groupsTake back an invitation link. POST /v2/channel-messages/{id}/removegroupsRemove another member’s message from a channel. POST /v2/communities/{id}/posts/{post}/removegroupsRemove a post from a group. DELETE /v2/communities/{id}/members/{member}groupsKick a member from a group. PUT /v2/communities/{id}/members/{member}/timeoutgroupsMute a member. DELETE /v2/communities/{id}/members/{member}/timeoutgroupsLift a timeout. GET /v2/communities/{id}/bansgroupsA group's running bans. PUT /v2/communities/{id}/bans/{member}groupsBan a member. DELETE /v2/communities/{id}/bans/{member}groupsLift a ban. GET /v2/communities/{id}/loggroupsThe leadership’s log: who removed what and why. POST /v2/communitiesgroupsFound a group. Answers with its id; you are its founder. PUT /v2/communities/{id}groupsChange a group you lead. Whatever you leave out stays. Bots GET /v2/eventsreadThe events from the bot's groups since an event, page by page. GET /v2/events/streamreadThe events from the bot's groups as they happen (server-sent events). GET /v2/me/commandsreadThe bot's commands. PUT /v2/me/commandswriteSet the bot's commands, all at once. POST /v2/interactions/{id}/replywriteAnswer a command or a button. POST /v2/channels/{id}/voicewriteTake a seat in a voice channel to play music or sound. Discover GET /v2/tagsreadThe tags that are trending right now. GET /v2/searchreadA search over posts, names, short names and tags. GET /v2/emojisreadThe instance’s own emojis, with the address of their pictures. GIFs and videos GET /v2/mediareadShared GIFs or videos, most used first. GET /v2/media/minemediaYour own media library, newest first. GET /v2/media/{id}readA GIF or video, yours or a shared one. POST /v2/media/uploadsmediaStart an upload. PUT /v2/media/uploads/{upload}mediaSend a piece of the file. POST /v2/media/{id}mediaChange one of your GIFs or videos. DELETE /v2/media/{id}mediaRemove one of your GIFs or videos. Your account GET /v2/mereadYour own profile, with the id the other paths expect. GET /v2/feedreadYour own feed, the way the application puts it together. POST /v2/me/pictureswriteUpload a picture, as its bytes. Answers with id and url; you then use the id as profile picture, banner or in a post. PUT /v2/me/profileprofileChange your profile: name, about, profile picture, banner and profile colour. Whatever you leave out stays. GET /v2/me/emojisreadYour own emojis. POST /v2/me/emojis/picturesprofileUpload the picture for an own emoji, as its bytes. POST /v2/me/emojisprofileCreate an own emoji. Answers with all your emojis. DELETE /v2/me/emojis/{name}profileRemove an own emoji. Answers with the rest. PUT /v2/me/emojis/sharingprofileSet whether your followers may use your emojis in their own texts. GET /v2/me/webhookswebhooksYour webhooks with their state. POST /v2/me/webhookswebhooksCreate a webhook. Answers with id and the secret for the signatures, this once only. DELETE /v2/me/webhooks/{id}webhooksDelete a webhook. POST /v2/me/webhooks/{id}/testwebhooksSend a test to a webhook. Notifications GET /v2/notificationsreadYour notifications, newest first. POST /v2/notifications/readwriteMark your notifications as read. Messages GET /v2/conversationsreadYour inbox: one row per conversation, the most recent first. GET /v2/conversations/{with}/messagesreadThe messages of one conversation, newest first. POST /v2/conversations/{with}/messageswriteSend a message in a conversation. POST /v2/conversations/{with}/readwriteMark every message of a conversation as read. DELETE /v2/conversations/{with}/messages/{id}writeDelete one of your messages. POST /v2/conversations/{with}/plannedwritePlan a message for later. Answers with the id of the planned message. GET /v2/me/planned-messagesreadYour own messages still to be sent, in order of their time. POST /v2/me/planned-messages/{id}/sendwriteSend a held or failed planned message now. DELETE /v2/me/planned-messages/{id}writeDelete a planned message before it is sent. Relations POST /v2/relationswriteLike, save, repost, follow, join, block, mute, depending on kind. GET /v2/profiles/{handle}/followersreadWho follows a profile, newest first. GET /v2/profiles/{handle}/followingreadWhom a profile follows, newest first. GET /v2/me/relationsreadWhom you blocked, muted, or blocked from messaging only, newest first. Collections GET /v2/me/collectionsreadYour collections with the number of their posts. POST /v2/me/collectionswriteCreate a collection. Answers with its id. PUT /v2/me/collections/{id}writeRename a collection. DELETE /v2/me/collections/{id}writeDelete a collection. GET /v2/me/collections/{id}/postsreadThe posts of a collection, as in the saved tab. POST /v2/me/collections/{id}/postswritePut a post into a collection or take it out. Gifts GET /v2/partner/quotareadWhat’s left in your quota to give away. GET /v2/partner/giftsreadWhat you’ve given from your quota, to whom and when – newest first. POST /v2/partner/giftsgiftsGive plan months or sparks from your quota to a member. GET /v2/gift-dropsreadYour gifts under posts: how many places are still open and how they were paid for. POST /v2/gift-dropsgiftsPublish a post with gifts for others to claim.
The way in The first request of every program: does the key work, and what may it do?
GET /v2API version and name of this instance.
Right read with ETag since v2.0 Without a slash at the end: https://api.tellmelo.com/v2/ redirects to https://api.tellmelo.com/v2 with 308, and not every program follows.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2"Answer Answers with one Service
Example {
"name": "tellmelo",
"version": "2.20",
"scope": "read write",
"rateLimit": {
"limit": 120,
"remaining": 117
},
"docs": "/developers/docs",
"spec": "/api/v2/openapi.json"
}Possible statuses: 200304401429
Posts Reading public posts, publishing your own and removing them again.
GET /v2/postsThe public posts, newest first.
Right read pageable with ETag since v2.0 On public paths, counts.likes and counts.reposts are always 0 and pinned is false.
Posts in groups aren’t here but under /communities/{id}/posts.
Parameters Name Type Meaning limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts?limit=20"Answer Answers with a page of Post
Example {
"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,
"ai": "without"
}
],
"poll": {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
},
"quotes": null,
"continues": null,
"counts": {
"replies": 4,
"likes": 31,
"reposts": 2
},
"pinned": false,
"giftDrop": {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
},
"createdAt": 1758624000000
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304401429
GET /v2/posts/{id}A single post, by its id.
Right read with ETag since v2.0 On public paths, counts.likes and counts.reposts are always 0 and pinned is false.
Posts in groups aren’t here but under /communities/{id}/posts.
Parameters Name Type Meaning idin the path stringrequired The id of a post.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"Answer Answers with one Post
Example {
"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,
"ai": "without"
}
],
"poll": {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
},
"quotes": null,
"continues": null,
"counts": {
"replies": 4,
"likes": 31,
"reposts": 2
},
"pinned": false,
"giftDrop": {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
},
"createdAt": 1758624000000
}Possible statuses: 200304400401404429
POST /v2/postsPublish a post.
A post needs text or a poll. Length, poll options and pace are set by the instance; beyond that you get 400 or 429.
Attach images, a GIF or a video with media. A GIF or video stands alone. You may use other members’ shared GIFs and videos on tellmelo.
A post for close friends or with a co-author goes out right away, not in a group and not scheduled. You can’t do both at once.
Parameters Name Type Meaning textin the body stringoptional The text of the post, reply or message. communityin the body stringoptional The id of the group whose feed channel the post goes to; it must be on, and you need the permission for it. Without it the post stands outside any group. quotesin the body stringoptional The id of the post this one quotes. pollin the body string[]optional The answer options as a list of texts. mediain the body string[]optional IDs of images uploaded in the app, or of a GIF or video from the media library (since 2.14). audiencein the body stringoptional Who sees the post: everyone who may see it, close only your close friends.everyoneclose coauthorin the body stringoptional The id of an account you invite as co-author. You must follow each other.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"The bees are back in the garden 🐝 #garden","audience":"everyone"}' \
"https://api.tellmelo.com/v2/posts"Answer Answers with one Created
Example {
"id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"scheduledFor": null,
"deleteAt": null
}Possible statuses: 200400401403429
DELETE /v2/posts/{id}Remove one of your own posts.
Parameters Name Type Meaning idin the path stringrequired The id of a post.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/me/scheduledYour posts that aren’t out yet, and what they’re waiting for.
Right read with ETag since v2.12 Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/scheduled"Answer Answers with a page of ScheduledPost
Example {
"items": [
{
"id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"text": "Market day tomorrow – see you at the bee stand! #garden",
"communityId": null,
"publishAt": 1758710400000,
"deleteAt": null,
"waitingFor": "time",
"createdAt": 1758624000000
}
],
"next": null
}Possible statuses: 200304401429
POST /v2/posts/{id}/scheduleChange when a scheduled post goes out, or when a post deletes itself.
Your own posts only. While a post’s gifts aren’t paid for, it can’t be scheduled.
Parameters Name Type Meaning idin the path stringrequired The id of a post. publishAtin the body integeroptional When the scheduled post goes out, in milliseconds since 1970. deleteAtin the body integeroptional When the post deletes itself, in milliseconds since 1970.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/schedule"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/posts/{id}/editChange the text of one of your posts.
Only within the editing window your plan gives you. Scheduled posts can’t be edited.
Parameters Name Type Meaning idin the path stringrequired The id of a post. textin the body stringrequired The text of the post, reply or message.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"The bees are back in the garden 🐝🌻 #garden"}' \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/edit"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/posts/{id}/reply-settingsWho may reply to your own post, whether replies wait for approval, and slow mode.
Right read with ETag since v2.19 Parameters Name Type Meaning idin the path stringrequired The id of a post.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/reply-settings"Answer Answers with one ReplySettings
Example {
"audience": "following",
"approval": false,
"slow": "auto"
}Possible statuses: 200304400401404429
PUT /v2/posts/{id}/reply-settingsChange the reply settings of your own post. Whatever you leave out stays.
Your own posts only.
Parameters Name Type Meaning idin the path stringrequired The id of a post. audiencein the body stringoptional Who may reply: everyone, accounts you follow, those mentioned, or nobody.allfollowingmentionednobody approvalin the body booleanoptional Whether replies only appear once you approve them. slowin the body stringoptional Slow mode: auto turns it on by itself when many replies come in, on always, off never.autoonoff
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"audience":"following","approval":false,"slow":"auto"}' \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/reply-settings"Answer Answers with one ReplySettings
Example {
"audience": "following",
"approval": false,
"slow": "auto"
}Possible statuses: 200400401403404429
POST /v2/posts/{id}/coauthorAccept or decline an invitation to co-author a post.
Parameters Name Type Meaning idin the path stringrequired The id of a post. acceptin the body booleanrequired true accepts the invitation, false declines it.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"accept":true}' \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/coauthor"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
DELETE /v2/posts/{id}/coauthorStep back as co-author, or as the author take the co-author off the post.
For the co-author and the author of the post.
Parameters Name Type Meaning idin the path stringrequired The id of a post.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/coauthor"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/posts/{id}/pinPin your own post to the top of your profile, or unpin it.
Only your own visible posts. How many can be pinned depends on the plan.
Parameters Name Type Meaning idin the path stringrequired The id of a post. activein the body booleanrequired true pins the post, false unpins it.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"active":true}' \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/pin"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
Replies Replies under a post, as a list with parentId.
GET /v2/posts/{id}/repliesThe replies to a post, without blocked accounts.
Right read pageable with ETag since v2.0 The list is flat and in order of writing; parentId turns it into a tree. A page always holds whole threads. Replies from blocked accounts are left out.
Parameters Name Type Meaning idin the path stringrequired The id of a post. limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies?limit=20"Answer Answers with a page of Reply
Example {
"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,
"giftDrop": null,
"createdAt": 1758624600000,
"postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"parentId": null
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304400401404429
POST /v2/posts/{id}/repliesReply to a post.
In slow mode, one reply per person every 10 minutes, otherwise 429. The author and accounts they follow are exempt.
With media at most one image, GIF or video.
Parameters Name Type Meaning idin the path stringrequired The id of a post. textin the body stringrequired The text of the post, reply or message. parentIdin the body stringoptional The id of the reply this one answers. Without it, straight to the post. mediain the body string[]optional IDs of images uploaded in the app, or of a GIF or video from the media library (since 2.14). publishAtin the body integeroptional When the reply should go out, in milliseconds since 1970. Without it, it goes out right away.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"Same here, the lavender is full of them."}' \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies"Answer Answers with one Created
Example {
"id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"scheduledFor": null,
"deleteAt": null
}Possible statuses: 200400401403404429
POST /v2/replies/{id}/editChange the text of one of your replies.
Parameters Name Type Meaning idin the path stringrequired The id of the reply. textin the body stringrequired The text of the post, reply or message.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"Same here, the lavender and the clover are full of them."}' \
"https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/edit"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
DELETE /v2/replies/{id}Remove one of your replies.
Parameters Name Type Meaning idin the path stringrequired The id of the reply.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/replies/{id}/likeUpvote a reply (a like is an upvote since replies are voted up and down), or take the upvote back; a downvote stays.
Right write since v2.12 deprecated Deprecated since 2.19: use POST /replies/{id}/vote. This route stays for now.
Parameters Name Type Meaning idin the path stringrequired The id of the reply. activein the body booleanrequired true sets the relation, false removes it.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"active":true}' \
"https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/like"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/replies/{id}/voteVote a reply up or down, or take your vote back. Answers with your vote and the score after it.
Parameters Name Type Meaning idin the path stringrequired The id of the reply. votein the body stringrequired up votes up, down votes down, none takes your vote back.updownnone
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"vote":"up"}' \
"https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/vote"Answer Answers with one ReplyVote
Example {
"vote": "up",
"score": 12
}Possible statuses: 200400401403404429
POST /v2/replies/{id}/pickHighlight a reply under your own post as the best one, or take the highlight back.
Only under your own posts, and only replies directly to the post. A new highlight replaces the old one.
Parameters Name Type Meaning idin the path stringrequired The id of the reply. activein the body booleanrequired true highlights the reply, false takes the highlight back.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"active":true}' \
"https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/pick"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/posts/{id}/replies/waitingThe replies waiting for approval under a post: all of them under your own post, otherwise only your own.
Right read with ETag since v2.19 Whether replies wait is set by the author in the reply settings.
Parameters Name Type Meaning idin the path stringrequired The id of a post.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies/waiting"Answer Answers with a page of Reply
Example {
"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,
"giftDrop": null,
"createdAt": 1758624600000,
"postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"parentId": null
}
],
"next": null
}Possible statuses: 200304400401404429
POST /v2/replies/{id}/decideApprove or decline a waiting reply under your own post. A declined reply is deleted.
Parameters Name Type Meaning idin the path stringrequired The id of the reply. approvein the body booleanrequired true approves the reply, false declines it.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"approve":true}' \
"https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/decide"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/posts/{id}/replies/plannedYour own replies planned for later under a post.
Right read with ETag since v2.19 You plan a reply with publishAt when replying. At most 20 planned replies at a time.
Parameters Name Type Meaning idin the path stringrequired The id of a post.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies/planned"Answer Answers with a page of PlannedReply
Example {
"items": [
{
"id": "3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
"parentId": null,
"text": "Count me in for Saturday!",
"publishAt": 1758710400000,
"state": "waiting"
}
],
"next": null
}Possible statuses: 200304400401404429
PUT /v2/me/planned-replies/{id}Change the text or time of a planned reply. A failed one waits again afterwards.
Parameters Name Type Meaning idin the path stringrequired The id of the planned reply. textin the body stringoptional The text of the post, reply or message. publishAtin the body integeroptional When the reply should go out, in milliseconds since 1970. Without it, it goes out right away.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"See you there!","publishAt":1758700000000}' \
"https://api.tellmelo.com/v2/me/planned-replies/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/me/planned-replies/{id}/sendSend a planned reply right away.
Parameters Name Type Meaning idin the path stringrequired The id of the planned reply.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/planned-replies/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9/send"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
DELETE /v2/me/planned-replies/{id}Delete a planned reply.
Parameters Name Type Meaning idin the path stringrequired The id of the planned reply.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/planned-replies/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
Polls A poll is a post whose poll is set. Voting has a path of its own.
POST /v2/posts/{id}/voteTake part in a poll.
Votes per option are null until you have voted or the poll ends. total is always there.
Parameters Name Type Meaning idin the path stringrequired The id of a post. optionin the body integerrequired Which option, counted from 0. For multiple choice, call once per option. retractin the body booleanoptional true withdraws the vote.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"option":0}' \
"https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/vote"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
Profiles Public profiles by their short name, and what they have posted.
GET /v2/profiles/{handle}A profile, by its short name.
Right read with ETag since v2.0 Parameters Name Type Meaning handlein the path stringrequired The short name of a profile, in any mix of capitals.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/profiles/mara"Answer Answers with one Profile
Example {
"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
}Possible statuses: 200304400401404429
GET /v2/profiles/{handle}/postsThe public posts of one profile, newest first.
Right read pageable with ETag since v2.0 On public paths, counts.likes and counts.reposts are always 0 and pinned is false.
Posts in groups aren’t here but under /communities/{id}/posts.
Parameters Name Type Meaning handlein the path stringrequired The short name of a profile, in any mix of capitals. limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/profiles/mara/posts?limit=20"Answer Answers with a page of Post
Example {
"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,
"ai": "without"
}
],
"poll": {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
},
"quotes": null,
"continues": null,
"counts": {
"replies": 4,
"likes": 31,
"reposts": 2
},
"pinned": false,
"giftDrop": {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
},
"createdAt": 1758624000000
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304400401404429
GET /v2/profiles/{handle}/eventsThe upcoming events of a profile, soonest first.
Right read with ETag since v2.19 Only while the profile’s plan includes events. Nothing between accounts that blocked each other.
Parameters Name Type Meaning handlein the path stringrequired The short name of a profile, in any mix of capitals.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/profiles/mara/events"Answer Answers with a page of Event
Example {
"items": [
{
"id": "2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b",
"title": "Seed swap",
"startsAt": 1758883200000,
"endsAt": 1758890400000,
"place": "Community garden",
"description": "Bring seeds, take seeds.",
"signups": {
"count": 14,
"going": true
}
}
],
"next": null
}Possible statuses: 200304400401404429
POST /v2/me/eventsCreate an event. Answers with its id.
Needs a plan with events, otherwise 403. How many can be upcoming depends on the plan.
Parameters Name Type Meaning titlein the body stringrequired The title. startsAtin the body integerrequired Start, in milliseconds since 1970. endsAtin the body integeroptional End, in milliseconds since 1970. Optional. placein the body stringoptional Where it takes place. descriptionin the body stringoptional A description. signupsin the body booleanoptional Whether people can sign up. Needs a plan with sign-ups. capacityin the body integeroptional How many can sign up at most. Without it, no limit.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"title":"Seed swap","startsAt":1758700000000,"place":"Community garden","signups":true,"capacity":30}' \
"https://api.tellmelo.com/v2/me/events"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403429
PUT /v2/me/events/{id}Change one of your events. All fields are set anew.
An event that has already started keeps its start.
Parameters Name Type Meaning idin the path stringrequired The id of the event. titlein the body stringrequired The title. startsAtin the body integerrequired Start, in milliseconds since 1970. endsAtin the body integeroptional End, in milliseconds since 1970. Optional. placein the body stringoptional Where it takes place. descriptionin the body stringoptional A description. signupsin the body booleanoptional Whether people can sign up. Needs a plan with sign-ups. capacityin the body integeroptional How many can sign up at most. Without it, no limit.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"title":"Seed swap","startsAt":1758700000000,"place":"Community garden","signups":true,"capacity":30}' \
"https://api.tellmelo.com/v2/me/events/2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
DELETE /v2/me/events/{id}Delete one of your events.
Parameters Name Type Meaning idin the path stringrequired The id of the event.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/events/2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/me/events/{id}/signupsWho signed up for one of your events.
Right read with ETag since v2.19 Parameters Name Type Meaning idin the path stringrequired The id of the event.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/events/2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b/signups"Answer Answers with a page of EventSignup
Example {
"items": [
{
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"at": 1758624000000
}
],
"next": null
}Possible statuses: 200304400401404429
POST /v2/events/{id}/signupSign up for an event or sign off.
Only for events with sign-ups, not your own. When it is full, 409.
Parameters Name Type Meaning idin the path stringrequired The id of the event. goingin the body booleanrequired true signs you up, false signs you off.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"going":true}' \
"https://api.tellmelo.com/v2/events/2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b/signup"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
Groups The open groups and your own, their posts, members, roles and invitation links.
GET /v2/communitiesThe open groups of this instance; with mine=true your account’s groups.
Right read with ETag since v2.0 Sorted by member count and not paged; next is always null.
Parameters Name Type Meaning limitin the query integeroptional Entries per page: 20 by default, at most 50. minein the query booleanoptional true for your account’s groups, internal and hidden ones too, by name.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities?limit=20"Answer Answers with a page of Community
Example {
"items": [
{
"id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
"name": "Urban Gardening",
"handle": "urbangardening",
"description": "Balconies, allotments, rooftops: whatever grows.",
"tags": [
"garden",
"bees"
],
"members": 312,
"joinPolicy": "open",
"visibility": "open",
"feedChannel": true,
"sparks": 24,
"perks": [
"tint",
"welcome"
],
"membership": {
"leader": null,
"roles": [
"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
],
"permissions": [
"attach",
"invite",
"send",
"view"
],
"mutedUntil": null
}
}
],
"next": null
}Possible statuses: 200304401429
GET /v2/communities/{id}A single group, by its id.
Right read with ETag since v2.0 Internal and hidden groups only when your account is a member.
Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"Answer Answers with one Community
Example {
"id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
"name": "Urban Gardening",
"handle": "urbangardening",
"description": "Balconies, allotments, rooftops: whatever grows.",
"tags": [
"garden",
"bees"
],
"members": 312,
"joinPolicy": "open",
"visibility": "open",
"feedChannel": true,
"sparks": 24,
"perks": [
"tint",
"welcome"
],
"membership": {
"leader": null,
"roles": [
"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
],
"permissions": [
"attach",
"invite",
"send",
"view"
],
"mutedUntil": null
}
}Possible statuses: 200304400401404429
GET /v2/communities/{id}/postsThe posts of a group’s feed channel, newest first.
Right read pageable with ETag since v2.0 On public paths, counts.likes and counts.reposts are always 0 and pinned is false.
If the feed channel is off, the path answers 409 with feed_off.
Parameters Name Type Meaning idin the path stringrequired The id of a group. limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/posts?limit=20"Answer Answers with a page of Post
Example {
"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,
"ai": "without"
}
],
"poll": {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
},
"quotes": null,
"continues": null,
"counts": {
"replies": 4,
"likes": 31,
"reposts": 2
},
"pinned": false,
"giftDrop": {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
},
"createdAt": 1758624000000
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304400401404429
GET /v2/communities/{id}/membersThe members of a group with their roles.
Right read with ETag since v2.15 The leadership first, then by highest role; at most 300.
Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/members"Answer Answers with a page of GroupMember
Example {
"items": [
{
"id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
"handle": "jon",
"name": "Jon",
"bot": false,
"leader": null,
"roles": [
"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
],
"mutedUntil": null
}
],
"next": null
}Possible statuses: 200304400401404429
GET /v2/communities/{id}/rolesThe roles of a group, the highest first, @everyone last.
Right read with ETag since v2.15 Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/roles"Answer Answers with a page of Role
Example {
"items": [
{
"id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"name": "Gardeners",
"everyone": false,
"color": "green",
"permissions": [
"attach",
"invite",
"send",
"view"
],
"members": 24,
"editable": true,
"selfable": false
}
],
"next": null
}Possible statuses: 200304400401404429
GET /v2/communities/{id}/bellWhich notifications a group sends you.
Right read with ETag since v2.15 Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bell"Answer Answers with one Bell
Example {
"level": "important"
}Possible statuses: 200304400401404429
GET /v2/invites/{code}The group behind an invitation link, before joining.
Right read with ETag since v2.15 Parameters Name Type Meaning codein the path stringrequired The code of an invitation link, the end of its address.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/invites/k7Qm2xPa"Answer Answers with one InvitePreview
Example {
"community": {
"id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
"name": "Urban Gardening",
"members": 312,
"rules": [
"Be kind.",
"No advertising."
]
},
"member": false
}Possible statuses: 200304400401404429
PUT /v2/roles/{id}/selfTake or put down a self-assignable role.
Only roles the leadership offers as self-assignable (selfable), and only for your own account.
Parameters Name Type Meaning idin the path stringrequired The id of a role. activein the body booleanoptional false takes the role away; otherwise it is given.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"active":true}' \
"https://api.tellmelo.com/v2/roles/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8/self"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/communities/{id}/emojisA group's own emojis.
Right read with ETag since v2.20 Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/emojis"Answer Answers with a page of GroupEmoji
Example {
"items": [
{
"name": "seedling",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false
}
],
"next": null
}Possible statuses: 200304400401404429
PUT /v2/communities/{id}/bellSet which notifications a group sends you.
Parameters Name Type Meaning idin the path stringrequired The id of a group. levelin the body stringrequired Which notifications come.allimportantoff
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"level":"important"}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bell"Answer Answers with one Bell
Example {
"level": "important"
}Possible statuses: 200400401403404429
POST /v2/invites/{code}/joinJoin a group with an invitation link.
Parameters Name Type Meaning codein the path stringrequired The code of an invitation link, the end of its address. rulesin the body booleanoptional true if you accept the group’s rules; needed when it has any.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/invites/k7Qm2xPa/join"Answer Answers with one Joined
Example {
"community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"
}Possible statuses: 200400401403404429
GET /v2/communities/{id}/botsThe bots of a group with what their role allows.
Right read with ETag since v2.19 Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bots"Answer Answers with a page of GroupBot
Example {
"items": [
{
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "gardenbot",
"name": "Garden bot",
"description": "Reminds the group of watering days.",
"permissions": [
"send",
"view"
]
}
],
"next": null
}Possible statuses: 200304400401404429
Channels The channels of your groups and their chat: reading, writing, marking as read.
GET /v2/communities/{id}/channelsThe channels of a group you can see, in their order.
Right read with ETag since v2.15 The feed channel (kind: feed) is only here while it is on; its posts come through /communities/{id}/posts.
Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/channels"Answer Answers with a page of Channel
Example {
"items": [
{
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
"kind": "chat",
"name": "harvest",
"topic": "What came in this week",
"category": {
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Garden",
"symbol": {
"emoji": null,
"icon": null,
"image": null,
"color": null,
"shape": null
}
},
"unread": 3,
"permissions": [
"view",
"send"
],
"symbol": {
"emoji": "🌻",
"icon": null,
"image": null,
"color": "amber",
"shape": "circle"
}
}
],
"next": null
}Possible statuses: 200304400401404429
GET /v2/channels/{id}/messagesThe messages of a chat channel, newest first.
Right read pageable with ETag since v2.15 Up to 50 messages a page. Messages of accounts you blocked or that blocked you are left out.
Parameters Name Type Meaning idin the path stringrequired The id of a channel. cursorin the query stringoptional The next of the previous answer. Without it, from the start. threadin the query stringoptional The message whose thread is read: it and its replies instead of the chat.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/messages"Answer Answers with a page of ChannelMessage
Example {
"items": [
{
"id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
"text": "@jon the first tomatoes are ripe 🍅",
"author": {
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"bot": false
},
"media": [
{
"url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"kind": "image",
"poster": null,
"ai": "without"
}
],
"replyTo": "72b3c4d5-e6f7-4081-92a3-b4c5d6e7f809",
"roleColor": "green",
"threadOf": null,
"threadCount": 3,
"card": null,
"buttons": [],
"createdAt": 1758631200000
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304400401404429
POST /v2/channels/{id}/messagesWrite a message in a chat channel.
@name notifies a member, @everyone with the permission for it everyone, at most six times an hour.
Parameters Name Type Meaning idin the path stringrequired The id of a channel. textin the body stringoptional The text of the post, reply or message. replyToin the body stringoptional The id of the message in the same channel you are answering. mediain the body string[]optional IDs of images uploaded in the app, or of a GIF or video from the media library (since 2.14). threadin the body stringoptional The chat message whose thread is replied in; without it the message goes into the chat. cardin the body objectoptional A card { title, text, color, fields: [{ name, value }] }, at most 10 fields. buttonsin the body object[]optional Up to 5 buttons, each { id, label, style } with style primary, secondary or danger. A press arrives as an interaction event.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"Who has seeds to swap?"}' \
"https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/messages"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
POST /v2/channels/{id}/readMark a chat channel as read up to a point in time.
Parameters Name Type Meaning idin the path stringrequired The id of a channel. atin the body integerrequired Up to when it is read, in milliseconds, usually the createdAt of the newest message.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/read"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
DELETE /v2/channel-messages/{id}Delete one of your messages in a chat channel.
Only your own messages; others’ messages are removed by the leadership with the groups permission.
Parameters Name Type Meaning idin the path stringrequired The id of a message in a chat channel.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/channel-messages/61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/communities/{id}/voiceWho is in a group’s voice channels right now, per channel.
Right read with ETag since v2.19 Only channels you may see. Without a media server, the list is empty.
Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/voice"Answer Answers with a page of VoiceRoom
Example {
"items": [
{
"channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
"people": [
{
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"muted": false,
"deaf": false,
"camera": false,
"screen": true
}
]
}
],
"next": null
}Possible statuses: 200304400401404429
Running groups What a group’s settings can do in the app, with the groups permission. What your account may do is decided by the group as in the app: leadership, roles and their rank.
POST /v2/communities/{id}/emojisGive the group an emoji.
Only who may manage the group's channels. The picture is uploaded like one of your own emojis (POST /me/emojis/pictures); a name is taken only once across all emojis.
Parameters Name Type Meaning idin the path stringrequired The id of a group. namein the body stringrequired The name you write the emoji with, as :name:. picturein the body stringrequired The id from POST /me/emojis/pictures.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"seedling","picture":"8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/emojis"Answer Answers with a page of GroupEmoji
Example {
"items": [
{
"name": "seedling",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false
}
],
"next": null
}Possible statuses: 200400401403404429
DELETE /v2/communities/{id}/emojis/{name}Remove an emoji from the group.
Parameters Name Type Meaning idin the path stringrequired The id of a group. namein the path stringrequired The name of the emoji, without colons.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/emojis/seedling"Answer Answers with a page of GroupEmoji
Example {
"items": [
{
"name": "seedling",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false
}
],
"next": null
}Possible statuses: 200400401403404429
POST /v2/communities/{id}/rolesCreate a role.
Only roles below your own highest and only permissions you have yourself; the leadership stands above all.
Parameters Name Type Meaning idin the path stringrequired The id of a group. namein the body stringoptional The role’s name; @everyone keeps its own. colorin the body stringoptional The colour; empty for none.indigovioletroseambergreenteal permissionsin the body string[]optional The permissions: view, send, attach, post_feed, invite, mention_everyone, moderate, timeout_members, kick_members, ban_members, manage_channels, manage_roles. selfablein the body booleanoptional true: members take the role themselves. Only for roles that allow no more than taking part (view, send, attach, voice_connect, voice_speak, voice_video).
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Gardeners","permissions":["view","send","invite"],"selfable":false}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/roles"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
PUT /v2/roles/{id}Change a role’s name, colour and permissions.
Replaces name, colour and permissions; what you leave out becomes empty.
Only roles below your own highest and only permissions you have yourself; the leadership stands above all.
Parameters Name Type Meaning idin the path stringrequired The id of a role. namein the body stringoptional The role’s name; @everyone keeps its own. colorin the body stringoptional The colour; empty for none.indigovioletroseambergreenteal permissionsin the body string[]optional The permissions: view, send, attach, post_feed, invite, mention_everyone, moderate, timeout_members, kick_members, ban_members, manage_channels, manage_roles. selfablein the body booleanoptional true: members take the role themselves. Only for roles that allow no more than taking part (view, send, attach, voice_connect, voice_speak, voice_video).
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Gardeners","permissions":["view","send","invite"],"selfable":false}' \
"https://api.tellmelo.com/v2/roles/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
DELETE /v2/roles/{id}Delete a role.
Parameters Name Type Meaning idin the path stringrequired The id of a role.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/roles/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
PUT /v2/communities/{id}/roles/orderSet the rank of the roles.
Parameters Name Type Meaning idin the path stringrequired The id of a group. rolesin the body string[]required The ids of all roles below your own highest, the highest first; for the leadership all except @everyone.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/roles/order"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
PUT /v2/roles/{id}/members/{member}Give a member a role or take it away.
Parameters Name Type Meaning idin the path stringrequired The id of a role. memberin the path stringrequired The id of a member’s account. activein the body booleanoptional false takes the role away; otherwise it is given.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"active":true}' \
"https://api.tellmelo.com/v2/roles/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8/members/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/communities/{id}/channelsCreate a chat channel.
Parameters Name Type Meaning idin the path stringrequired The id of a group. namein the body stringoptional The name, without #; empty for the name the app gives in each language. topicin the body stringoptional The topic shown above the channel. categoryin the body stringoptional The id of the category the channel goes into; empty for none. emojiin the body stringoptional An emoji as the symbol. iconin the body stringoptional A symbol of the app’s set, by its name.homehashmegaphonevolumemessagehelpinfobellcalendarbookbookmarkpinshieldstarheartsparklesflamezaptrophygiftrocketlightbulbcodewrenchbriefcasegraduationpalettecamerafilmmusicgamepaddumbbellleafflowerpawsunmooncloudglobemapcoffeepizzasmile imagein the body stringoptional The id of a picture you uploaded with /media/emoji. colorin the body stringoptional The tile’s colour.brandindigovioletroseambergreentealred shapein the body stringoptional The tile’s shape; a circle without one.circlesquaretrianglediamondhexagonoctagonshieldstar
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"harvest","emoji":"🌻","color":"amber"}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/channels"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
PUT /v2/channels/{id}Change a channel’s name, topic and category.
Replaces name, topic and category; what you leave out becomes empty.
Parameters Name Type Meaning idin the path stringrequired The id of a channel. namein the body stringoptional The name, without #; empty for the name the app gives in each language. topicin the body stringoptional The topic shown above the channel. categoryin the body stringoptional The id of the category the channel goes into; empty for none. emojiin the body stringoptional An emoji as the symbol. iconin the body stringoptional A symbol of the app’s set, by its name.homehashmegaphonevolumemessagehelpinfobellcalendarbookbookmarkpinshieldstarheartsparklesflamezaptrophygiftrocketlightbulbcodewrenchbriefcasegraduationpalettecamerafilmmusicgamepaddumbbellleafflowerpawsunmooncloudglobemapcoffeepizzasmile imagein the body stringoptional The id of a picture you uploaded with /media/emoji. colorin the body stringoptional The tile’s colour.brandindigovioletroseambergreentealred shapein the body stringoptional The tile’s shape; a circle without one.circlesquaretrianglediamondhexagonoctagonshieldstar
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"harvest","emoji":"🌻","color":"amber"}' \
"https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
DELETE /v2/channels/{id}Delete a chat channel with its messages.
The feed channel cannot be deleted, only switched off.
Parameters Name Type Meaning idin the path stringrequired The id of a channel.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
PUT /v2/communities/{id}/channels/orderSet the order of the categories and chat channels.
Parameters Name Type Meaning idin the path stringrequired The id of a group. categoriesin the body string[]required The ids of all the group’s categories in their new order. channelsin the body string[]required The ids of all the group’s chat channels in their new order.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/channels/order"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
PUT /v2/communities/{id}/channels/shapeSet the shape of all the group’s channel symbols.
The group’s leadership only.
Parameters Name Type Meaning idin the path stringrequired The id of a group. shapein the body stringoptional The shape of all the group’s symbols; left out, each channel has its own.circlesquaretrianglediamondhexagonoctagonshieldstar
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/channels/shape"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/channels/{id}/overridesWhat roles may do differently in a channel than in the group.
Right groups with ETag since v2.15 Parameters Name Type Meaning idin the path stringrequired The id of a channel.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/overrides"Answer Answers with a page of ChannelOverride
Example {
"items": [
{
"role": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"allow": [
"send"
],
"deny": []
}
],
"next": null
}Possible statuses: 200304400401403404429
PUT /v2/channels/{id}/overrides/{role}Set what a role may do differently in a channel.
Not for roles at or above your own highest.
Parameters Name Type Meaning idin the path stringrequired The id of a channel. rolein the path stringrequired The id of a role. allowin the body string[]optional What the role may do here as well: in a chat view, send, attach, mention_everyone, moderate, in the feed channel view and post_feed. denyin the body string[]optional What the role may not do here, from the same permissions. Both lists empty remove the difference.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"allow":["view"],"deny":["send"]}' \
"https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/overrides/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/communities/{id}/categoriesCreate a category for channels.
Parameters Name Type Meaning idin the path stringrequired The id of a group. namein the body stringrequired The category’s name. emojiin the body stringoptional An emoji as the symbol. iconin the body stringoptional A symbol of the app’s set, by its name.homehashmegaphonevolumemessagehelpinfobellcalendarbookbookmarkpinshieldstarheartsparklesflamezaptrophygiftrocketlightbulbcodewrenchbriefcasegraduationpalettecamerafilmmusicgamepaddumbbellleafflowerpawsunmooncloudglobemapcoffeepizzasmile imagein the body stringoptional The id of a picture you uploaded with /media/emoji. colorin the body stringoptional The tile’s colour.brandindigovioletroseambergreentealred
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Garden","emoji":"🌻","color":"amber"}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/categories"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
PUT /v2/categories/{id}Rename a category.
Parameters Name Type Meaning idin the path stringrequired The id of a category. namein the body stringrequired The category’s name. emojiin the body stringoptional An emoji as the symbol. iconin the body stringoptional A symbol of the app’s set, by its name.homehashmegaphonevolumemessagehelpinfobellcalendarbookbookmarkpinshieldstarheartsparklesflamezaptrophygiftrocketlightbulbcodewrenchbriefcasegraduationpalettecamerafilmmusicgamepaddumbbellleafflowerpawsunmooncloudglobemapcoffeepizzasmile imagein the body stringoptional The id of a picture you uploaded with /media/emoji. colorin the body stringoptional The tile’s colour.brandindigovioletroseambergreentealred
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Garden","emoji":"🌻","color":"amber"}' \
"https://api.tellmelo.com/v2/categories/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
DELETE /v2/categories/{id}Delete a category.
Its channels stay, without a category.
Parameters Name Type Meaning idin the path stringrequired The id of a category.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/categories/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
PUT /v2/communities/{id}/feedSwitch a group’s feed channel on or off.
Off, the posts stay stored but only their authors can see them.
Parameters Name Type Meaning idin the path stringrequired The id of a group. onin the body booleanrequired true switches the feed channel on, false off.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/feed"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/communities/{id}/invitesA group’s invitation links that still work.
Right groups with ETag since v2.15 The leadership sees all, everyone else only their own.
Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/invites"Answer Answers with a page of InviteLink
Example {
"items": [
{
"code": "k7Qm2xPa",
"url": "https://tellmelo.com/groups?join=k7Qm2xPa",
"createdBy": {
"id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
"handle": "jon",
"name": "Jon",
"bot": false
},
"createdAt": 1758624000000,
"expiresAt": 1759228800000,
"uses": 3,
"maxUses": 10
}
],
"next": null
}Possible statuses: 200304400401403404429
POST /v2/communities/{id}/invitesCreate an invitation link.
A link works only as long as you may invite, and goes when you leave.
Parameters Name Type Meaning idin the path stringrequired The id of a group. daysin the body integeroptional How many days the link works; without it, until it is taken back.1730 usesin the body integeroptional How often the link can be used; without it, any number of times.151025100
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"days":7,"uses":10}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/invites"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
DELETE /v2/invites/{code}Take back an invitation link.
Parameters Name Type Meaning codein the path stringrequired The code of an invitation link, the end of its address.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/invites/k7Qm2xPa"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/channel-messages/{id}/removeRemove another member’s message from a channel.
Logged in the group’s log and at most 60 an hour, as in the app.
Parameters Name Type Meaning idin the path stringrequired The id of a message in a chat channel.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/channel-messages/61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/remove"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/communities/{id}/posts/{post}/removeRemove a post from a group.
Logged in the group’s log and at most 60 an hour, as in the app.
Parameters Name Type Meaning idin the path stringrequired The id of a group. postin the path stringrequired The id of a post. reasonin the body stringrequired The reason the member reads.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"reason":"Advertising for another site, despite rule 2."}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/posts/post/remove"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
DELETE /v2/communities/{id}/members/{member}Kick a member from a group.
A kick since 2.16: the member can join again. Whoever should stay out is banned.
Only with the permission for it and only for members below your own highest role; co-managers only as the founder.
Logged in the group’s log and at most 60 an hour, as in the app.
Parameters Name Type Meaning idin the path stringrequired The id of a group. memberin the path stringrequired The id of a member’s account. reasonin the body stringrequired The reason the member reads.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"reason":"Advertising for another site, despite rule 2."}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/members/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
PUT /v2/communities/{id}/members/{member}/timeoutMute a member.
A new timeout replaces one running. Leaving and joining again does not end it.
Only with the permission for it and only for members below your own highest role; co-managers only as the founder.
Logged in the group’s log and at most 60 an hour, as in the app.
Parameters Name Type Meaning idin the path stringrequired The id of a group. memberin the path stringrequired The id of a member’s account. secondsin the body integerrequired How long, in seconds.60300600360086400604800 reasonin the body stringoptional A reason the member reads; optional.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"seconds":600}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/members/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d/timeout"Answer Answers with one Until
Example {
"until": 1758624600000
}Possible statuses: 200400401403404429
DELETE /v2/communities/{id}/members/{member}/timeoutLift a timeout.
Parameters Name Type Meaning idin the path stringrequired The id of a group. memberin the path stringrequired The id of a member’s account.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/members/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d/timeout"Answer Answers with one Until
Example {
"until": 1758624600000
}Possible statuses: 200400401403404429
GET /v2/communities/{id}/bansA group's running bans.
Right groups with ETag since v2.16 Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bans"Answer Answers with a page of Ban
Example {
"items": [
{
"member": {
"id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
"handle": "jon",
"name": "Jon",
"bot": false
},
"until": 1759228800000,
"createdAt": 1758624000000,
"by": "Mara 🌻"
}
],
"next": null
}Possible statuses: 200304400401403404429
PUT /v2/communities/{id}/bans/{member}Ban a member.
Without days the ban lasts until it is lifted.
Only with the permission for it and only for members below your own highest role; co-managers only as the founder.
Logged in the group’s log and at most 60 an hour, as in the app.
Parameters Name Type Meaning idin the path stringrequired The id of a group. memberin the path stringrequired The id of a member’s account. daysin the body integeroptional How long, in days; leave it out for a ban without an end.1730 reasonin the body stringrequired The reason the member reads.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"days":7,"reason":"Advertising for another site, despite rule 2."}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bans/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d"Answer Answers with one Until
Example {
"until": 1758624600000
}Possible statuses: 200400401403404429
DELETE /v2/communities/{id}/bans/{member}Lift a ban.
Parameters Name Type Meaning idin the path stringrequired The id of a group. memberin the path stringrequired The id of a member’s account.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bans/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/communities/{id}/logThe leadership’s log: who removed what and why.
Right groups with ETag since v2.15 Parameters Name Type Meaning idin the path stringrequired The id of a group.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/log"Answer Answers with a page of LogEntry
Example {
"items": [
{
"id": "8f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918",
"action": "message_removed",
"member": {
"id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
"handle": "jon",
"name": "Jon",
"bot": false
},
"reason": "",
"by": "Mara 🌻",
"createdAt": 1758710400000
}
],
"next": null
}Possible statuses: 200304400401403404429
POST /v2/communitiesFound a group. Answers with its id; you are its founder.
Needs the permission groups. Without saying, the group is internal and free to join; a hidden one by invitation only. Whether members may found groups is up to the operator.
Parameters Name Type Meaning namein the body stringrequired The name, at most 60 characters. descriptionin the body stringoptional The description, at most 240 characters. handlein the body stringoptional The handle for @# mentions and the link: 3 to 30 lowercase letters, digits or _. tagsin the body string[]optional Up to 5 #tags, what the group is about. joinPolicyin the body stringoptional How people join: open freely, application by applying, invite by invitation only.openapplicationinvite visibilityin the body stringoptional Who sees the group: open everyone, internal only members its content, hidden only members at all.openinternalhidden
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Seed swap","handle":"seedswap","tags":["garden","seeds"],"joinPolicy":"open","visibility":"open"}' \
"https://api.tellmelo.com/v2/communities"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403429
PUT /v2/communities/{id}Change a group you lead. Whatever you leave out stays.
Needs the permission groups and the group’s leadership. Leadership, dissolving and spark perks stay in the app.
Parameters Name Type Meaning idin the path stringrequired The id of a group. namein the body stringoptional The name, at most 60 characters. descriptionin the body stringoptional The description, at most 240 characters. handlein the body stringoptional The handle for @# mentions and the link: 3 to 30 lowercase letters, digits or _. tagsin the body string[]optional Up to 5 #tags, what the group is about. joinPolicyin the body stringoptional How people join: open freely, application by applying, invite by invitation only.openapplicationinvite visibilityin the body stringoptional Who sees the group: open everyone, internal only members its content, hidden only members at all.openinternalhidden imagein the body stringoptional The id of an uploaded picture (POST /me/pictures) as the group picture. Empty removes it. bannerin the body stringoptional The id of an uploaded picture as the group’s banner. Empty removes it.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Seed swap","handle":"seedswap","tags":["garden","seeds"],"joinPolicy":"open","visibility":"open"}' \
"https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
Bots What happens in a bot's groups, in real time: as a stream, page by page, or delivered to an address.
GET /v2/eventsThe events from the bot's groups since an event, page by page.
Only with a bot's token. A channel's events only if the bot may see it.
Events are kept for a day. next is the number of the last one, as since for the next page.
Parameters Name Type Meaning sincein the query stringoptional The number of the last event the bot already has. Without it, the stream starts now and the list at the oldest.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/events?since=0"Answer Answers with a page of BotEvent
Example {
"items": [
{
"id": "4711",
"type": "message.created",
"community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
"channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
"createdAt": 1758634800000,
"data": {
"message": {
"id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
"text": "/dice 6",
"author": {
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"bot": false
},
"media": 0,
"replyTo": null,
"threadOf": null,
"createdAt": 1758634800000
}
}
}
],
"next": null
}Possible statuses: 200401429
GET /v2/events/streamThe events from the bot's groups as they happen (server-sent events).
Right read with ETag since v2.20 The connection stays open and closes after ten minutes; the client reconnects and sends Last-Event-ID.
Only with a bot's token. A channel's events only if the bot may see it.
Parameters Name Type Meaning sincein the query stringoptional The number of the last event the bot already has. Without it, the stream starts now and the list at the oldest.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/events/stream?since=0"Answer Answers with one BotEvent
Example {
"id": "4711",
"type": "message.created",
"community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
"channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
"createdAt": 1758634800000,
"data": {
"message": {
"id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
"text": "/dice 6",
"author": {
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"bot": false
},
"media": 0,
"replyTo": null,
"threadOf": null,
"createdAt": 1758634800000
}
}
}Possible statuses: 200304401429
GET /v2/me/commandsThe bot's commands.
Right read with ETag since v2.20 Only with a bot's token. A channel's events only if the bot may see it.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/commands"Answer Answers with a page of BotCommand
Example {
"items": [
{
"name": "dice",
"description": "Rolls a die"
}
],
"next": null
}Possible statuses: 200304401429
PUT /v2/me/commandsSet the bot's commands, all at once.
Replaces all commands; an empty list removes them. In chats the bot may see, the input field offers them after “/”.
Parameters Name Type Meaning commandsin the body object[]required Up to 25 commands, each { name, description }.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"commands":[{"name":"dice","description":"Rolls a die"}]}' \
"https://api.tellmelo.com/v2/me/commands"Answer Answers with a page of BotCommand
Example {
"items": [
{
"name": "dice",
"description": "Rolls a die"
}
],
"next": null
}Possible statuses: 200400401403429
POST /v2/interactions/{id}/replyAnswer a command or a button.
Within 15 minutes of the command or interaction event; with private, only whoever used the command or button sees the answer.
Parameters Name Type Meaning idin the path stringrequired The id from the event (data.interaction). textin the body stringoptional The text of the post, reply or message. privatein the body booleanoptional true: only whoever used the command or button sees the answer, for a day.cardin the body objectoptional A card { title, text, color, fields: [{ name, value }] }, at most 10 fields. buttonsin the body object[]optional Up to 5 buttons, each { id, label, style } with style primary, secondary or danger. A press arrives as an interaction event.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"You rolled a 4.","private":true}' \
"https://api.tellmelo.com/v2/interactions/9b8c7d6e-5f4a-4b3c-8d2e-1f0a9b8c7d6e/reply"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
POST /v2/channels/{id}/voiceTake a seat in a voice channel to play music or sound.
Only with a bot's token, as the bot's role allows in the channel. The program connects with a LiveKit SDK and sends its sound as a microphone; everyone else sets its volume for themselves.
Parameters Name Type Meaning idin the path stringrequired The id of a channel.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/voice"Answer Answers with one VoiceSeat
Example {
"url": "wss://voice.example.org",
"token": "eyJhbGciOiJIUzI1NiJ9…",
"iceServers": [
{
"urls": [
"stun:turn.example.org:3478"
]
}
],
"speak": true,
"video": false
}Possible statuses: 200400401403404429
Discover Trends, search and the instance’s custom emojis.
GET /v2/tagsThe tags that are trending right now.
Right read with ETag since v2.0 At most 10 trending tags by score: each use counts 1 and halves every 3 days, an account counts at most 3 per day. posts is the rounded score. limit only shortens the list. Tags the team highlights can stand further up.
Parameters Name Type Meaning limitin the query integeroptional Entries per page: 20 by default, at most 50.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/tags?limit=10"Answer Answers with a page of Tag
Example {
"items": [
{
"tag": "garden",
"posts": 58
}
],
"next": null
}Possible statuses: 200304401429
GET /v2/searchA search over posts, names, short names and tags.
Right read with ETag since v2.0 Searches public content only: posts outside groups, profiles and tags. limit applies per kind.
Parameters Name Type Meaning qin the query stringrequired The words being looked for. typein the query stringoptional Which kind of result. Without it, every kind.allpostsprofilestags limitin the query integeroptional Entries per page: 20 by default, at most 50.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/search?q=garden&type=posts"Answer Answers with one SearchResult
Example {
"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,
"ai": "without"
}
],
"poll": {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
},
"quotes": null,
"continues": null,
"counts": {
"replies": 4,
"likes": 31,
"reposts": 2
},
"pinned": false,
"giftDrop": {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
},
"createdAt": 1758624000000
}
],
"profiles": [
{
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"verified": true,
"accountKind": "person"
}
],
"tags": [
{
"tag": "garden",
"posts": 58
}
]
}Possible statuses: 200304400401429
GET /v2/emojisThe instance’s own emojis, with the address of their pictures.
Right read with ETag since v2.1 In texts an emoji appears as :name:. Replace it with the image from this list; unknown names stay text.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/emojis"Answer Answers with a page of Emoji
Example {
"items": [
{
"name": "tellmelo",
"url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
}
],
"next": null
}Possible statuses: 200304401429
GIFs and videos The media library: find shared GIFs and videos, upload and manage your own, and embed them on other websites.
GET /v2/mediaShared GIFs or videos, most used first.
Right read pageable with ETag since v2.14 Without accounts you blocked or that blocked you. Load url and poster with the key in the header, for posts on tellmelo.
For other websites only what has embed: its addresses work without a key, in any browser.
Parameters Name Type Meaning kindin the query stringoptional gif or video; gif when not given.gifvideoqin the query stringoptional Words in the name or the keywords. anywherein the query booleanoptional true: only what may appear on other websites too.limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/media?kind=gif&q=bees&anywhere=true&limit=20"Answer Answers with a page of MediaItem
Example {
"items": [
{
"id": "b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"kind": "gif",
"name": "Happy bees",
"keywords": "bees garden happy",
"width": 480,
"height": 270,
"seconds": 0,
"url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"poster": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918&poster=1",
"uploader": {
"handle": "mara",
"name": "Mara 🌻"
},
"mine": false,
"shared": true,
"anywhere": true,
"embed": {
"page": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"file": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/file",
"poster": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/poster",
"code": "<iframe src=\"https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918\" width=\"480\" height=\"300\" title=\"Happy bees\" style=\"border:0;max-width:100%\" loading=\"lazy\" allowfullscreen></iframe>"
}
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304400401429
GET /v2/media/mineYour own media library, newest first.
Right media pageable with ETag since v2.14 Parameters Name Type Meaning kindin the query stringoptional gif or video; gif when not given.gifvideoqin the query stringoptional Words in the name or the keywords. limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/media/mine?kind=gif&q=bees&limit=20"Answer Answers with a page of MediaItem
Example {
"items": [
{
"id": "b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"kind": "gif",
"name": "Happy bees",
"keywords": "bees garden happy",
"width": 480,
"height": 270,
"seconds": 0,
"url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"poster": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918&poster=1",
"uploader": {
"handle": "mara",
"name": "Mara 🌻"
},
"mine": false,
"shared": true,
"anywhere": true,
"embed": {
"page": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"file": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/file",
"poster": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/poster",
"code": "<iframe src=\"https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918\" width=\"480\" height=\"300\" title=\"Happy bees\" style=\"border:0;max-width:100%\" loading=\"lazy\" allowfullscreen></iframe>"
}
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304400401403429
GET /v2/media/{id}A GIF or video, yours or a shared one.
Right read with ETag since v2.14 Parameters Name Type Meaning idin the path stringrequired The ID of the GIF or video.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/media/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918"Answer Answers with one MediaItem
Example {
"id": "b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"kind": "gif",
"name": "Happy bees",
"keywords": "bees garden happy",
"width": 480,
"height": 270,
"seconds": 0,
"url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"poster": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918&poster=1",
"uploader": {
"handle": "mara",
"name": "Mara 🌻"
},
"mine": false,
"shared": true,
"anywhere": true,
"embed": {
"page": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"file": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/file",
"poster": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/poster",
"code": "<iframe src=\"https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918\" width=\"480\" height=\"300\" title=\"Happy bees\" style=\"border:0;max-width:100%\" loading=\"lazy\" allowfullscreen></iframe>"
}
}Possible statuses: 200304400401404429
POST /v2/media/uploadsStart an upload.
Then send the file in pieces of at most piece bytes to /media/uploads/{upload}. Without a new piece an upload ends after 15 minutes.
The app’s limits apply: GIFs up to 15 MB, videos by plan in size and length, GIFs per day, private GIFs, video points per week. Otherwise you get 409, 413 or 429.
Parameters Name Type Meaning kindin the body stringrequired gif or video; gif when not given.gifvideosizein the body integerrequired The size of the whole file in bytes. namein the body stringrequired The name it is found by: 2 to 40 characters. keywordsin the body stringoptional Keywords for the search, separated by spaces. sharedin the body booleanoptional true: shared with everyone on tellmelo.anywherein the body booleanoptional true: shared and allowed on other websites too. Only together with shared.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"kind":"gif","size":2400000,"name":"Happy bees","keywords":"bees garden","shared":true,"anywhere":false}' \
"https://api.tellmelo.com/v2/media/uploads"Answer Answers with one UploadStarted
Example {
"upload": "e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b",
"piece": 4194304
}Possible statuses: 200400401403429
PUT /v2/media/uploads/{upload}Send a piece of the file.
The body is the piece itself (application/octet-stream), not JSON. If it doesn’t follow on, you get 409 with received: carry on from there. After the last piece the file is converted; the answer then has item.
Parameters Name Type Meaning uploadin the path stringrequired The upload from the start. offsetin the query integerrequired Where the piece starts in the file, in bytes; 0 for the first.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/octet-stream" \
--data-binary @piece \
"https://api.tellmelo.com/v2/media/uploads/e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b?offset=0"Answer Answers with one UploadPiece
Example {
"received": 4194304,
"item": null
}Possible statuses: 200400401403404429
POST /v2/media/{id}Change one of your GIFs or videos.
Parameters Name Type Meaning idin the path stringrequired The ID of the GIF or video. namein the body stringoptional The name it is found by: 2 to 40 characters. keywordsin the body stringoptional Keywords for the search, separated by spaces. sharedin the body booleanoptional true: shared with everyone on tellmelo.anywherein the body booleanoptional true: shared and allowed on other websites too. Only together with shared.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Happy bees","anywhere":true}' \
"https://api.tellmelo.com/v2/media/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
DELETE /v2/media/{id}Remove one of your GIFs or videos.
Posts that already show it keep it. On other websites it disappears within minutes.
Parameters Name Type Meaning idin the path stringrequired The ID of the GIF or video.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/media/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
Your account Your profile, your feed, your own emojis and your webhooks.
GET /v2/meYour own profile, with the id the other paths expect.
Right read with ETag since v2.0 Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me"Answer Answers with one Profile
Example {
"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
}Possible statuses: 200304401429
GET /v2/feedYour own feed, the way the application puts it together.
Right read pageable since v2.0 No ETag, because the order keeps changing. A list you started stays the same until its end.
Parameters Name Type Meaning tabin the query stringoptional Which feed: for-you, following, latest or bookmarks. latest by default.for-youfollowinglatestbookmarks tagin the query stringoptional Only posts about this tag: written with it or recognised in them by the server. Without it, no filter. limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/feed?tab=following&limit=20"Answer Answers with a page of Post
Example {
"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,
"ai": "without"
}
],
"poll": {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
},
"quotes": null,
"continues": null,
"counts": {
"replies": 4,
"likes": 31,
"reposts": 2
},
"pinned": false,
"giftDrop": {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
},
"createdAt": 1758624000000
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200400401429
POST /v2/me/picturesUpload a picture, as its bytes. Answers with id and url; you then use the id as profile picture, banner or in a post.
PNG, JPEG, WebP or GIF, recognised by its first bytes; stored anew without metadata. A picture used nowhere is deleted later.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/octet-stream" \
--data-binary @picture.png \
"https://api.tellmelo.com/v2/me/pictures"Answer Answers with one Picture
Example {
"id": "8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"
}Possible statuses: 200401403429
PUT /v2/me/profileChange your profile: name, about, profile picture, banner and profile colour. Whatever you leave out stays.
Needs the permission profile. Your @name stays in the app: it is also your sign-in name.
Parameters Name Type Meaning namein the body stringoptional The display name, at most 60 characters. aboutin the body stringoptional The about text. avatarin the body stringoptional The id of an uploaded picture as profile picture. Empty removes it. bannerin the body stringoptional The id of an uploaded picture as banner. Empty removes it. colorin the body stringoptional The profile colour, with a plan. null removes it.indigovioletrosecoralamberlimegreentealskyslatesandnight
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Mara 🌻","about":"Gardening in the city.","avatar":"8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"}' \
"https://api.tellmelo.com/v2/me/profile"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403429
GET /v2/me/emojisYour own emojis.
Right read with ETag since v2.19 Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/emojis"Answer Answers with a page of OwnEmoji
Example {
"items": [
{
"name": "sunflower",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false,
"resting": false
}
],
"next": null
}Possible statuses: 200304401429
POST /v2/me/emojis/picturesUpload the picture for an own emoji, as its bytes.
Moving emojis need a plan. Too large after converting, the picture is refused.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/octet-stream" \
--data-binary @picture.png \
"https://api.tellmelo.com/v2/me/emojis/pictures"Answer Answers with one EmojiPicture
Example {
"id": "8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false
}Possible statuses: 200401403429
POST /v2/me/emojisCreate an own emoji. Answers with all your emojis.
How many emojis you can create depends on the plan.
Parameters Name Type Meaning namein the body stringrequired The name you write the emoji with, as :name:. picturein the body stringrequired The id from POST /me/emojis/pictures.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"sunflower","picture":"8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"}' \
"https://api.tellmelo.com/v2/me/emojis"Answer Answers with a page of OwnEmoji
Example {
"items": [
{
"name": "sunflower",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false,
"resting": false
}
],
"next": null
}Possible statuses: 200400401403429
DELETE /v2/me/emojis/{name}Remove an own emoji. Answers with the rest.
Parameters Name Type Meaning namein the path stringrequired The name of the emoji, without colons.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/emojis/sunflower"Answer Answers with a page of OwnEmoji
Example {
"items": [
{
"name": "sunflower",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false,
"resting": false
}
],
"next": null
}Possible statuses: 200400401403404429
PUT /v2/me/emojis/sharingSet whether your followers may use your emojis in their own texts.
Parameters Name Type Meaning sharedin the body booleanrequired true shares your emojis with your followers, false doesn’t.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"shared":true}' \
"https://api.tellmelo.com/v2/me/emojis/sharing"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403429
GET /v2/me/webhooksYour webhooks with their state.
Right webhooks with ETag since v2.19 Needs the permission webhooks. Webhooks come with an organisation plan or as a partner.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/webhooks"Answer Answers with a page of Webhook
Example {
"items": [
{
"id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
"url": "https://example.org/tellmelo-hook",
"kinds": [
"reply",
"mention"
],
"active": true,
"lastStatus": 200,
"lastAt": 1758624000000,
"failures": 0
}
],
"next": null
}Possible statuses: 200304401403429
POST /v2/me/webhooksCreate a webhook. Answers with id and the secret for the signatures, this once only.
Right webhooks since v2.19 Every delivery is signed with the secret (X-Tellmelo-Signature). Keep it; it is not shown again.
Parameters Name Type Meaning urlin the body stringrequired An HTTPS address outside local networks, without credentials. kindsin the body string[]required What the webhook is told about. Which kinds are open to you depends on your plan and partnership.replymentiongroup_mentionfollowlikerepostmessagequota_changedquota_giftdrop_claimeddrop_empty
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.org/tellmelo-hook","kinds":["reply","mention"]}' \
"https://api.tellmelo.com/v2/me/webhooks"Answer Answers with one WebhookCreated
Example {
"id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
"secret": "whsec_3f9a…"
}Possible statuses: 200400401403429
DELETE /v2/me/webhooks/{id}Delete a webhook.
Right webhooks since v2.19 Parameters Name Type Meaning idin the path stringrequired The id of the webhook.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/webhooks/1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/me/webhooks/{id}/testSend a test to a webhook.
Right webhooks since v2.19 Parameters Name Type Meaning idin the path stringrequired The id of the webhook.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/webhooks/1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b/test"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
Notifications What happened around your account, page by page.
GET /v2/notificationsYour notifications, newest first.
Right read pageable with ETag since v2.0 Reading marks nothing as read; POST /notifications/read does. Events of the same kind on the same post share one row; more says how many.
Parameters Name Type Meaning limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/notifications?limit=20"Answer Answers with a page of Notification
Example {
"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"
}Possible statuses: 200304401429
POST /v2/notifications/readMark your notifications as read.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/notifications/read"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200401403429
Messages Your inbox and conversations. A conversation is named after the other account.
GET /v2/conversationsYour inbox: one row per conversation, the most recent first.
Right read pageable with ETag since v2.0 Parameters Name Type Meaning limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/conversations?limit=20"Answer Answers with a page of Conversation
Example {
"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"
}Possible statuses: 200304401429
GET /v2/conversations/{with}/messagesThe messages of one conversation, newest first.
Right read pageable with ETag since v2.0 Reading marks nothing as read; POST /conversations/{with}/read does.
Parameters Name Type Meaning within the path stringrequired The id of the other account. A conversation has no id of its own. limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages?limit=20"Answer Answers with a page of Message
Example {
"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"
}Possible statuses: 200304400401404429
POST /v2/conversations/{with}/messagesSend a message in a conversation.
The app’s rules apply: whoever blocked you can’t be reached, and the other person’s settings count.
Images, GIFs and videos can’t be attached to messages through the API, only in the app.
Parameters Name Type Meaning within the path stringrequired The id of the other account. A conversation has no id of its own. textin the body stringrequired The text of the post, reply or message. replyToin the body stringoptional The id of an earlier message in this conversation that this one answers. Since 2.2.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"See you on Saturday at the market!"}' \
"https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/conversations/{with}/readMark every message of a conversation as read.
Parameters Name Type Meaning within the path stringrequired The id of the other account. A conversation has no id of its own.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/read"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
DELETE /v2/conversations/{with}/messages/{id}Delete one of your messages.
Your own messages only, and only within 24 hours of sending.
Parameters Name Type Meaning within the path stringrequired The id of the other account. A conversation has no id of its own. idin the path stringrequired The id of the message.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages/7c6b5a49-3827-4165-9f0e-d1c2b3a49586"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
POST /v2/conversations/{with}/plannedPlan a message for later. Answers with the id of the planned message.
Needs a plan that includes planned messages, otherwise 403. With end-to-end encryption on both sides it only works in the app.
Parameters Name Type Meaning within the path stringrequired The id of the other account. A conversation has no id of its own. textin the body stringrequired The text of the post, reply or message. sendAtin the body integerrequired When the message is sent, in milliseconds since 1970.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"Happy birthday! 🎂","sendAt":1758700000000}' \
"https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/planned"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403404429
GET /v2/me/planned-messagesYour own messages still to be sent, in order of their time.
Right read with ETag since v2.19 Parameters Name Type Meaning within the query stringoptional Only the messages to this account (its id).
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/planned-messages"Answer Answers with a page of PlannedMessage
Example {
"items": [
{
"id": "3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
"to": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"text": "Happy birthday! 🎂",
"sendAt": 1758710400000,
"state": "waiting"
}
],
"next": null
}Possible statuses: 200304401429
POST /v2/me/planned-messages/{id}/sendSend a held or failed planned message now.
Parameters Name Type Meaning idin the path stringrequired The id of the planned message.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/planned-messages/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9/send"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
DELETE /v2/me/planned-messages/{id}Delete a planned message before it is sent.
Parameters Name Type Meaning idin the path stringrequired The id of the planned message.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/planned-messages/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
Relations Like, save, repost, follow, join, block: one path, set and removed with active. Since 2.19 also the lists: followers, following, and your own blocks and mutes.
POST /v2/relationsLike, save, repost, follow, join, block, mute, depending on kind.
target is a post for like, save and repost, a group for join, an account for follow, block and mute. active: false removes the relation.
Parameters Name Type Meaning kindin the body stringrequired Which relation: like, save, repost, follow, join, block or mute (since 2.2).likesaverepostfollowjoinblockmute targetin the body stringrequired The id of the post, profile or group, depending on kind. activein the body booleanoptional true sets the relation, false removes it.
Example request 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://api.tellmelo.com/v2/relations"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403429
GET /v2/profiles/{handle}/followersWho follows a profile, newest first.
Right read pageable with ETag since v2.19 Parameters Name Type Meaning handlein the path stringrequired The short name of a profile, in any mix of capitals. limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/profiles/mara/followers?limit=20"Answer Answers with a page of ProfileBrief
Example {
"items": [
{
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"verified": true,
"accountKind": "person"
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304400401404429
GET /v2/profiles/{handle}/followingWhom a profile follows, newest first.
Right read pageable with ETag since v2.19 Parameters Name Type Meaning handlein the path stringrequired The short name of a profile, in any mix of capitals. limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/profiles/mara/following?limit=20"Answer Answers with a page of ProfileBrief
Example {
"items": [
{
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"verified": true,
"accountKind": "person"
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304400401404429
GET /v2/me/relationsWhom you blocked, muted, or blocked from messaging only, newest first.
Right read pageable with ETag since v2.19 Only your own lists. Setting and removing goes through POST /relations.
Parameters Name Type Meaning kindin the query stringrequired block blocked, mute muted, dm_block blocked from messaging only.blockmutedm_blocklimitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/relations?kind=mute&limit=20"Answer Answers with a page of ProfileBrief
Example {
"items": [
{
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"verified": true,
"accountKind": "person"
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304400401429
Collections Sort saved posts into your own collections. A post can be in several; taken out of a collection it stays saved.
GET /v2/me/collectionsYour collections with the number of their posts.
Right read with ETag since v2.19 Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/collections"Answer Answers with a page of Collection
Example {
"items": [
{
"id": "6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718",
"name": "Recipes",
"count": 12
}
],
"next": null
}Possible statuses: 200304401429
POST /v2/me/collectionsCreate a collection. Answers with its id.
How many collections you can create depends on the plan.
Parameters Name Type Meaning namein the body stringrequired The name, at most 40 characters. Unique per account, ignoring case.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Recipes"}' \
"https://api.tellmelo.com/v2/me/collections"Answer Answers with one Made
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}Possible statuses: 200400401403429
PUT /v2/me/collections/{id}Rename a collection.
Parameters Name Type Meaning idin the path stringrequired The id of the collection. namein the body stringrequired The name, at most 40 characters. Unique per account, ignoring case.
Example request curl -X PUT \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"name":"Baking"}' \
"https://api.tellmelo.com/v2/me/collections/6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
DELETE /v2/me/collections/{id}Delete a collection.
The posts in it stay saved.
Parameters Name Type Meaning idin the path stringrequired The id of the collection.
Example request curl -X DELETE \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/collections/6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
GET /v2/me/collections/{id}/postsThe posts of a collection, as in the saved tab.
Right read pageable since v2.19 Parameters Name Type Meaning idin the path stringrequired The id of the collection. limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/me/collections/6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718/posts?limit=20"Answer Answers with a page of Post
Example {
"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,
"ai": "without"
}
],
"poll": {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
},
"quotes": null,
"continues": null,
"counts": {
"replies": 4,
"likes": 31,
"reposts": 2
},
"pinned": false,
"giftDrop": {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
},
"createdAt": 1758624000000
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200400401404429
POST /v2/me/collections/{id}/postsPut a post into a collection or take it out.
Putting a post in also saves it. Visible posts only.
Parameters Name Type Meaning idin the path stringrequired The id of the collection. postin the body stringrequired The id of the post. insidein the body booleanoptional true puts the post in (default), false takes it out.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"post":"5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1","inside":true}' \
"https://api.tellmelo.com/v2/me/collections/6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718/posts"Answer Answers with one Ok
Example {
"ok": true
}Possible statuses: 200400401403404429
Gifts Read a partner’s quota and give from it, put gifts under posts and keep an eye on them. Claiming stays with people in the app.
GET /v2/partner/quotaWhat’s left in your quota to give away.
Right read with ETag since v2.12 For partners with a quota only; everyone else gets 403.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/partner/quota"Answer Answers with one Quota
Example {
"months": 120,
"sparks": 500,
"looks": [
{
"id": "frame-gold",
"name": "Goldring",
"kind": "frame",
"quantity": 25
}
]
}Possible statuses: 200304401429
GET /v2/partner/giftsWhat you’ve given from your quota, to whom and when – newest first.
Right read pageable with ETag since v2.12 For partners with a quota only; everyone else gets 403.
Parameters Name Type Meaning limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/partner/gifts?limit=20"Answer Answers with a page of QuotaGift
Example {
"items": [
{
"item": "plan",
"quantity": 3,
"itemId": null,
"recipient": {
"handle": "jon",
"name": "Jon"
},
"createdAt": 1758627600000
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304401429
POST /v2/partner/giftsGive plan months or sparks from your quota to a member.
For partners with a quota only; everyone else gets 403.
Just like in the app, the member sees who the gift is from. At most 60 gifts per hour.
Parameters Name Type Meaning handlein the body stringrequired The @name of the member you’re giving to, with or without the @. itemin the body stringrequired plan for plan months, sparks for sparks, shop for a look from your stock (since 2.13).plansparksshopquantityin the body integeroptional How much: up to 12 months or 35 sparks per gift. itemIdin the body stringoptional For shop: the look’s ID as looks in the quota names it. One piece per gift; quantity does not apply.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"handle":"jon","item":"plan","quantity":3,"itemId":"frame-gold"}' \
"https://api.tellmelo.com/v2/partner/gifts"Answer Answers with one Quota
Example {
"months": 120,
"sparks": 500,
"looks": [
{
"id": "frame-gold",
"name": "Goldring",
"kind": "frame",
"quantity": 25
}
]
}Possible statuses: 200400401403429
GET /v2/gift-dropsYour gifts under posts: how many places are still open and how they were paid for.
Right read pageable with ETag since v2.12 Parameters Name Type Meaning limitin the query integeroptional Entries per page: 20 by default, at most 50. cursorin the query stringoptional The next of the previous answer. Without it, from the start.
Example request curl \
-H "Authorization: Bearer tm_key_…" \
"https://api.tellmelo.com/v2/gift-drops?limit=20"Answer Answers with a page of OwnGiftDrop
Example {
"items": [
{
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": false,
"postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"funding": "quota",
"createdAt": 1758624000000
}
],
"next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}Possible statuses: 200304401429
POST /v2/gift-dropsPublish a post with gifts for others to claim.
Free for the owner and team members with that permission, otherwise it comes out of your quota. Anything that would need paying is refused with 422 – paying only works in the app.
Claiming only works in the app, so no program can sweep up every place. How many are still open is in the post’s giftDrop.
Parameters Name Type Meaning textin the body stringoptional The text of the post, reply or message. communityin the body stringoptional The id of the group whose feed channel the post goes to; it must be on, and you need the permission for it. Without it the post stands outside any group. itemin the body stringrequired plan for plan months, sparks for sparks.plansparksquantityin the body integerrequired What each place holds: up to 12 months or 35 sparks. placesin the body integerrequired How many people, up to 10,000. audiencein the body stringoptional Who can claim: all everyone, followers only your followers, group only members of the group (only together with community).allfollowersgroup newAccountsin the body booleanoptional true lets accounts younger than 7 days claim too. Leave it out to keep them out.
Example request curl -X POST \
-H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"text":"Ten times three months of Supporter – first come, first served! 🎁","item":"plan","quantity":3,"places":10,"audience":"all","newAccounts":false}' \
"https://api.tellmelo.com/v2/gift-drops"Answer Answers with one DropCreated
Example {
"id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"funding": "quota"
}Possible statuses: 200400401403429
Objects All objects, field by field. [] means list.
ServiceThe answer of the root: who is answering, and what this key may do.
Field Type Meaning namestringAlways tellmelo. versionstringThe version of the API, for example 2.1. scopestringWhat this key may do: read or read write. rateLimitRateLimitThe budget of this key. docsstringWhere this documentation is, as a path on this instance. specstringWhere the machine-readable description is.
Example {
"name": "tellmelo",
"version": "2.20",
"scope": "read write",
"rateLimit": {
"limit": 120,
"remaining": 117
},
"docs": "/developers/docs",
"spec": "/api/v2/openapi.json"
}RateLimitThe budget of this key in the current minute.
Field Type Meaning limitintegerRequests per minute. remainingintegerHow many are left in this minute.
Example {
"limit": 120,
"remaining": 117
}PostA post, in the same shape everywhere.
Field Type Meaning idstringThe id of the post. textstringor null The text as written (null for a post that is only a poll or only pictures). kindstringWhat the post is.post — A post with text, pictures or a quote.poll — A post with a poll. authorProfileBriefWho wrote it. communityCommunityBriefor null The group it was written in (null outside every group). mediaMedia[]Its images, in order; empty if there are none. pollPollor null The poll (null if there is none). quotesstringor null The id of the post this one quotes. continuesstringor null The id of the post this one continues, as an addendum. countsCountsReplies, likes and reposts. pinnedbooleanWhether it is pinned to the top of its author’s profile. giftDropGiftDropor null Gifts to claim under the post (null if there are none). createdAtintegerWhen it was written.
Example {
"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,
"ai": "without"
}
],
"poll": {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
},
"quotes": null,
"continues": null,
"counts": {
"replies": 4,
"likes": 31,
"reposts": 2
},
"pinned": false,
"giftDrop": {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
},
"createdAt": 1758624000000
}ReplyA reply under a post: a post with two more fields.
Every field of Post
Field Type Meaning postIdstringThe post the whole conversation hangs off. parentIdstringor null The reply this one answers (null if it answers the post directly).
Example {
"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,
"giftDrop": null,
"createdAt": 1758624600000,
"postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"parentId": null
}ReplyVoteYour vote on a reply and its score.
Field Type Meaning votestringYour vote.up — Voted up.down — Voted down.none — No vote. scoreintegerUpvotes minus downvotes, also below zero.
Example {
"vote": "up",
"score": 12
}PlannedReplyOne of your replies planned for later.
Field Type Meaning idstringThe id of the planned reply. parentIdstringor null The reply it will answer (null if it answers the post directly). textstringThe text. publishAtintegerWhen it goes out. statestringIts state.waiting — Waiting for its time.failed — Could not be sent, for example because the post is gone.
Example {
"id": "3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
"parentId": null,
"text": "Count me in for Saturday!",
"publishAt": 1758710400000,
"state": "waiting"
}ReplySettingsThe reply settings of one of your posts.
Field Type Meaning audiencestringWho may reply.all — Everyone.following — Accounts you follow.mentioned — Those mentioned in the post.nobody — Nobody but you. approvalbooleanWhether replies wait for your approval. slowstringSlow mode.auto — Turns itself on when many replies come in.on — Always on.off — Off.
Example {
"audience": "following",
"approval": false,
"slow": "auto"
}CountsHow many replies, likes and reposts a post has.
Field Type Meaning repliesintegerReplies, all levels together. likesintegerLikes. repostsintegerReposts.
Example {
"replies": 4,
"likes": 31,
"reposts": 2
}PollThe poll of a post.
Field Type Meaning optionsPollOption[]The answers, in order. option in a vote counts from 0. totalintegerAll votes together, always present. multiplebooleanWhether more than one answer may be chosen. endsAtintegeror null When the poll ends (null if it runs without an end). runningbooleanWhether votes can still be cast. resultsVisiblebooleanWhether the votes per answer are shown (see votes). myVotesinteger[]The answers you chose, counted from 0.
Example {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
}PollOptionOne answer of a poll.
Field Type Meaning textstringThe answer. votesintegeror null Its votes (null while the results are held back).
Example {
"text": "Lavender",
"votes": 12
}ProfileBriefA profile as it appears inside other objects: as an author, in a search.
Field Type Meaning idstringThe id of the account: what /relations and /conversations/{with} expect. handlestringThe short name, without @, written the way the member chose it. namestringThe display name. It may contain emojis, including :name:. verifiedbooleanWhether the account is verified. accountKindstringWhat kind of account it is.person — A person.business — A business.association — A club or association.automated — An automated account, such as a bot.bot — A bot of groups, run by a program with its own key (since 2.18).
Example {
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"verified": true,
"accountKind": "person"
}ProfileA profile on its own, with its description and its followers.
Every field of ProfileBrief
Field Type Meaning aboutstringor null The description (null if there is none). websitestringor null The profile’s website (null if there is none). Since 2.3. websiteVerifiedbooleanWhether the website links back to this profile with rel=me, checked weekly. Since 2.3. followersintegerHow many accounts follow it. createdAtintegeror null When the account was created (null while the member hides the join date; since 2.9).
Example {
"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
}MembershipWhat your account is and may do in the group.
Field Type Meaning leaderstringor null Whether you founded the group or help lead it; null otherwise.founder — Founded it.manager — Co-leads it. rolesstring[]The ids of your roles, the highest first. permissionsstring[]What you may do in the group. mutedUntilintegeror null Until when a timeout mutes you here; null without one.
Example {
"leader": null,
"roles": [
"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
],
"permissions": [
"attach",
"invite",
"send",
"view"
],
"mutedUntil": null
}PersonA member, in short.
Field Type Meaning idstringThe account’s id. handlestringThe username, without @. namestringThe display name. botbooleanWhether the account is a bot (since 2.18).
Example {
"id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
"handle": "jon",
"name": "Jon",
"bot": false
}ChannelA channel of a group.
Field Type Meaning idstringThe id. kindstringWhich kind of channel.feed — The feed channel, whose posts are also in the public feed.chat — A chat.voice — A voice channel; talking works in the app only.hub — The group’s hub: its page with what it is. Always there, without messages. namestringor null The name without #; null for the name the app gives in each language. topicstringThe topic; empty if there is none. categoryChannelCategoryor null The category; null without one. unreadintegerHow many messages of others you have not read yet, up to 100. permissionsstring[]What you may do in this channel. symbolChannelSymbolIts symbol; the shape already the group’s when it sets one.
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
"kind": "chat",
"name": "harvest",
"topic": "What came in this week",
"category": {
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Garden",
"symbol": {
"emoji": null,
"icon": null,
"image": null,
"color": null,
"shape": null
}
},
"unread": 3,
"permissions": [
"view",
"send"
],
"symbol": {
"emoji": "🌻",
"icon": null,
"image": null,
"color": "amber",
"shape": "circle"
}
}ChannelCategoryThe category a channel is under.
Field Type Meaning idstringThe id. namestringThe name. symbolChannelSymbolIts symbol.
Example {
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Garden",
"symbol": {
"emoji": null,
"icon": null,
"image": null,
"color": null,
"shape": null
}
}ChannelSymbolA channel’s or category’s symbol: at most one of emoji, symbol and picture, otherwise the sign of its kind.
Field Type Meaning emojistringor null The emoji; null without one. iconstringor null The name of the symbol of the app’s set; null without one. imagestringor null The address of the own picture; null without one. colorstringor null The tile’s colour; null for that of its kind. shapestringor null The tile’s shape; null for a circle.
Example {
"emoji": "🌻",
"icon": null,
"image": null,
"color": "amber",
"shape": "circle"
}ChannelMessageA message in a chat channel.
Field Type Meaning idstringThe id. textstringor null The text (null for a message of only pictures or voice). authorPersonWho wrote it. mediaMedia[]Its pictures and voice messages; empty if there are none. replyTostringor null The id of the message it answers; null if none. roleColorstringor null The colour of the author's highest role that has one; null without. threadOfstringor null The message whose thread this one replies in; null in the chat. threadCountintegerHow many replies this message's thread has. cardobjector null A bot's card: title, text, color and fields; otherwise null. buttonsobject[]A bot's buttons: each id, label and style. createdAtintegerWhen it was written.
Example {
"id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
"text": "@jon the first tomatoes are ripe 🍅",
"author": {
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"bot": false
},
"media": [
{
"url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"kind": "image",
"poster": null,
"ai": "without"
}
],
"replyTo": "72b3c4d5-e6f7-4081-92a3-b4c5d6e7f809",
"roleColor": "green",
"threadOf": null,
"threadCount": 3,
"card": null,
"buttons": [],
"createdAt": 1758631200000
}RoleA role of a group.
Field Type Meaning idstringThe id. namestringor null The name; null for @everyone. everyonebooleanWhether it is @everyone, the role of all members. colorstringor null The colour: indigo, violet, rose, amber, green or teal; null without one. permissionsstring[]Its permissions. membersintegerHow many have it; for @everyone all members. editablebooleanWhether your account may change it. selfablebooleanWhether members take and put down the role themselves.
Example {
"id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"name": "Gardeners",
"everyone": false,
"color": "green",
"permissions": [
"attach",
"invite",
"send",
"view"
],
"members": 24,
"editable": true,
"selfable": false
}GroupMemberA member of a group with their roles.
Every field of Person
Field Type Meaning leaderstringor null Whether the member founded the group or helps lead it; null otherwise.founder — Founded it.manager — Co-leads it. rolesstring[]The ids of their roles, the highest first. mutedUntilintegeror null Until when a timeout mutes the member, if your account may give timeouts; null otherwise.
Example {
"id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
"handle": "jon",
"name": "Jon",
"bot": false,
"leader": null,
"roles": [
"4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
],
"mutedUntil": null
}ChannelOverrideWhat a role may do differently in a channel than in the group.
Field Type Meaning rolestringThe role’s id. allowstring[]What it may also do here. denystring[]What it may not do here.
Example {
"role": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"allow": [
"send"
],
"deny": []
}BellA group’s bell.
Field Type Meaning levelstringWhich notifications come.all — Every new post in the feed channel, and @everyone.important — The leadership’s posts in the feed channel, and @everyone.off — Nothing, unless you are mentioned with @name.
Example {
"level": "important"
}InviteLinkAn invitation link of a group.
Field Type Meaning codestringThe code. urlstringThe address to share. createdByPersonor null Who created it; null if the account is deleted. createdAtintegerWhen it was created. expiresAtintegeror null Until when it works; null without an end. usesintegerHow often it was used. maxUsesintegeror null How often it can be used; null for any number of times.
Example {
"code": "k7Qm2xPa",
"url": "https://tellmelo.com/groups?join=k7Qm2xPa",
"createdBy": {
"id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
"handle": "jon",
"name": "Jon",
"bot": false
},
"createdAt": 1758624000000,
"expiresAt": 1759228800000,
"uses": 3,
"maxUses": 10
}InvitePreviewWhere an invitation link leads.
Field Type Meaning communityInviteGroupThe group. memberbooleanWhether your account is a member already.
Example {
"community": {
"id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
"name": "Urban Gardening",
"members": 312,
"rules": [
"Be kind.",
"No advertising."
]
},
"member": false
}InviteGroupThe group behind an invitation link.
Field Type Meaning idstringThe id. namestringThe name. membersintegerHow many members it has. rulesstring[]Its rules, accepted when joining; empty if there are none.
Example {
"id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
"name": "Urban Gardening",
"members": 312,
"rules": [
"Be kind.",
"No advertising."
]
}JoinedJoining with an invitation link.
Field Type Meaning communitystringThe group’s id.
Example {
"community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"
}LogEntryAn entry in the leadership’s log.
Field Type Meaning idstringThe id. actionstringWhat happened.post_removed — A post.member_removed — A member removed, before 2.16 (kept out for 90 days).message_removed — A message in a chat channel.member_kicked — A kick.member_banned — A ban.member_unbanned — A ban lifted.member_timed_out — A timeout.timeout_lifted — A timeout lifted.voice_muted — Muted in a voice channel.voice_removed — Disconnected from a voice channel.bot_added — A bot was taken into the group (since 2.18).bot_removed — A bot was taken out of the group (since 2.18). memberPersonWhom it concerned. reasonstringThe reason; empty for messages and when none was given. bystringor null The name of who did it; null if the account is deleted. createdAtintegerWhen.
Example {
"id": "8f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918",
"action": "message_removed",
"member": {
"id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
"handle": "jon",
"name": "Jon",
"bot": false
},
"reason": "",
"by": "Mara 🌻",
"createdAt": 1758710400000
}BanA ban from a group.
Field Type Meaning memberPersonWho is banned. untilintegeror null Until when; null until it is lifted. createdAtintegeror null Since when; null for bans from before 2.16. bystringor null The name of who banned; null if unknown.
Example {
"member": {
"id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
"handle": "jon",
"name": "Jon",
"bot": false
},
"until": 1759228800000,
"createdAt": 1758624000000,
"by": "Mara 🌻"
}UntilWhen a timeout or ban ends.
Field Type Meaning untilintegeror null The time; null for a ban without an end or a timeout that was lifted.
Example {
"until": 1758624600000
}TagA tag and how many posts carry it.
Field Type Meaning tagstringThe tag, without #. postsintegerHow many recent posts carry it.
Example {
"tag": "garden",
"posts": 58
}SearchResultThree lists, possibly empty.
Field Type Meaning postsPost[]Matching posts, newest first. profilesProfileBrief[]Matching profiles, by short name. tagsTag[]Matching tags, most used first.
Example {
"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,
"ai": "without"
}
],
"poll": {
"options": [
{
"text": "Lavender",
"votes": 12
},
{
"text": "Sunflowers",
"votes": 7
},
{
"text": "Clover",
"votes": 3
}
],
"total": 22,
"multiple": false,
"endsAt": null,
"running": true,
"resultsVisible": true,
"myVotes": [
0
]
},
"quotes": null,
"continues": null,
"counts": {
"replies": 4,
"likes": 31,
"reposts": 2
},
"pinned": false,
"giftDrop": {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
},
"createdAt": 1758624000000
}
],
"profiles": [
{
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"verified": true,
"accountKind": "person"
}
],
"tags": [
{
"tag": "garden",
"posts": 58
}
]
}EmojiAn emoji of this instance.
Field Type Meaning namestringThe name, as it stands between the colons. urlstringThe address of the picture, relative to this instance.
Example {
"name": "tellmelo",
"url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
}NotificationA notification. One row can gather several events of the same kind.
Field Type Meaning idstringThe id of the notification. kindstringWhat happened.reply — Someone replied to you.like — Someone likes your post.reply_like — Someone upvotes your reply.duel — Someone challenges you to a Feed Duel, or your challenge has been played.reply_pick — The author of a post highlights your reply.repost — Someone shared your post.follow — Someone follows you.mention — Someone mentioned you.group_mention — Someone mentioned a group you lead; text is its name.channel_mention — Someone mentioned you in a chat channel of one of your groups, @everyone included; the member is the actor, the sentence names channel and group, never the message.message — Someone wrote you a message.scheduled — A scheduled post of yours has been published.video — A post of yours that waited for its video went out or became a draft again.reminder — A reminder about a saved post is due.report — What became of a report you sent in.moderation — A decision about your account: a warning, a restriction, an appeal.team — New work for the team (owners, admins and moderators only).reward — A reward for inviting is about to go or has gone.gift — A present from the team: a plan, or sparks for you or for a group you lead.present — A gift from a member: sparks or plan time; the member is the actor.spark — Sparks end soon, or a group you lead no longer has enough sparks for its perks.loyalty — About the loyalty rhythm: an active week counts or is one day short, a reward is new or about to fade.impact — How your posts from the first twelve hours did after a day, in one notification.discovery — An invitation to the discovery programme, or that a place there begins or ends.group_post — A new post in a group whose bell rings for it.group_moderation — A group’s leadership removed one of your posts, or you, from the group.group — Something a member did with you in a group: invited, admitted or turned you down, made you co-lead, handed the group over or dissolved it, or applied to your group; the member is the actor, the group’s name ends the sentence.coauthor — Someone invited you as co-author of a post.partner — A reminder from the partner programme, or the end of the partner badge.news — A new article in a region you follow.pick — A post of yours is up for post of the week or of the year, or it won.advent — A new door of the Advent calendar is open, one was opened, or today’s is still waiting.team_message — A message the tellmelo team wrote to chosen members.challenge — A new challenge of the week has begun.nudge — Once: a post nobody has answered yet, or the running challenge.signin — A computer asks whether you are signing in there right now. textstringor null Only for reports and moderation: the related text, otherwise null. actorActorWho did it. postIdstringor null The post it is about (null if it is about none). readbooleanWhether it has been marked as read. moreintegerHow many further events this row stands for, beyond the one named. createdAtintegerWhen it first happened. updatedAtintegerWhen it last gathered another event. The list is sorted by this.
Example {
"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
}ActorWho triggered a notification.
Field Type Meaning handlestringThe short name. namestringThe display name.
Example {
"handle": "jon",
"name": "Jon"
}ConversationOne row of your inbox.
Field Type Meaning withstringThe id of the other account: what /conversations/{with}/messages expects. handlestringTheir short name. namestringTheir display name. excerptstringor null The beginning of the last message (null if it has no text). truncatedbooleanWhether the excerpt was cut short. fromMebooleanWhether the last message is yours. lastMessageIdstringThe id of the last message. unreadintegerHow many of their messages you have not read yet. updatedAtintegerWhen the last message was written.
Example {
"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
}MessageA message in a conversation.
Field Type Meaning idstringThe id of the message. textstringor null The text (null for a message that is only pictures). fromstringThe id of the account that wrote it. tostringThe id of the account it was written to. readbooleanWhether the recipient has read it. mediaMedia[]Its images; empty if there are none. replyTostringor null The id of the message this one answers (null if it answers none). Since 2.2. createdAtintegerWhen it was sent.
Example {
"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
}PlannedMessageOne of your messages planned for later.
Field Type Meaning idstringThe id of the planned message. tostringThe id of the account receiving it. textstringor null The text, null with end-to-end encryption. sendAtintegerWhen it is sent. statestringIts state.waiting — Waiting for its time.held — Held because the plan ended. You can send it yourself or delete it.failed — Could not be sent.
Example {
"id": "3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
"to": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"text": "Happy birthday! 🎂",
"sendAt": 1758710400000,
"state": "waiting"
}ScheduledPostOne of your posts that isn’t out yet.
Field Type Meaning idstringThe id of the post. textstringor null The text. communityIdstringor null The group it appears in (null outside groups). publishAtintegeror null When it goes out (null while it’s waiting for something else). deleteAtintegeror null When it deletes itself (null: never). waitingForstringWhat it’s waiting for.time — Its time.review — Approval of a text written for review.check — The automatic moderation’s check.payment — Payment for its gifts. createdAtintegerWhen it was written.
Example {
"id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"text": "Market day tomorrow – see you at the bee stand! #garden",
"communityId": null,
"publishAt": 1758710400000,
"deleteAt": null,
"waitingFor": "time",
"createdAt": 1758624000000
}CollectionA collection of saved posts.
Field Type Meaning idstringThe id of the collection. namestringIts name. countintegerHow many posts are in it.
Example {
"id": "6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718",
"name": "Recipes",
"count": 12
}EventAn upcoming event of a profile.
Field Type Meaning idstringThe id of the event. titlestringThe title. startsAtintegerStart. endsAtintegeror null End, null without an end. placestringor null The place. descriptionstringor null The description. signupsEventSignupsor null The sign-ups, null without sign-ups.
Example {
"id": "2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b",
"title": "Seed swap",
"startsAt": 1758883200000,
"endsAt": 1758890400000,
"place": "Community garden",
"description": "Bring seeds, take seeds.",
"signups": {
"count": 14,
"going": true
}
}EventSignupsHow many have signed up.
Field Type Meaning countintegerThe number of sign-ups. goingbooleanWhether you have signed up.
Example {
"count": 14,
"going": true
}EventSignupSomeone who signed up for one of your events.
Field Type Meaning idstringThe id of the account. handlestringThe handle. namestringThe display name. atintegerWhen they signed up.
Example {
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"at": 1758624000000
}PictureAn uploaded picture.
Field Type Meaning idstringThe id of the picture. urlstringWhere it can be seen.
Example {
"id": "8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"
}EmojiPictureThe uploaded picture of an emoji.
Field Type Meaning idstringThe id of the picture. urlstringWhere it can be seen. animatedbooleanWhether it moves.
Example {
"id": "8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false
}OwnEmojiOne of your own emojis.
Field Type Meaning namestringIts name. urlstringIts picture. animatedbooleanWhether it moves. restingbooleanResting because the plan allows fewer emojis right now: it stays but can’t be used.
Example {
"name": "sunflower",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false,
"resting": false
}GroupEmojiAn emoji of a group.
Field Type Meaning namestringIts name. urlstringIts picture. animatedbooleanWhether it moves.
Example {
"name": "seedling",
"url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
"animated": false
}BotEventAn event in one of the bot's groups.
Field Type Meaning idstringIts number, ascending; it's how you continue (since, Last-Event-ID). typestringWhat happened.message.created — A message was written.message.deleted — A message was deleted.member.joined — Someone joined.member.left — Someone left or was removed.voice.joined — Someone joined a voice channel.command — Someone used one of the bot's commands.interaction — Someone pressed a button in one of the bot's messages. communitystringThe group. channelstringor null The channel; null for the whole group. createdAtintegerWhen it happened. dataobjectWhat belongs to it, by type: message, member (with reason), command or interaction.
Example {
"id": "4711",
"type": "message.created",
"community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
"channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
"createdAt": 1758634800000,
"data": {
"message": {
"id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
"text": "/dice 6",
"author": {
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"bot": false
},
"media": 0,
"replyTo": null,
"threadOf": null,
"createdAt": 1758634800000
}
}
}BotCommandA command of a bot.
Field Type Meaning namestringIts name, without “/”. descriptionstringWhat it does.
Example {
"name": "dice",
"description": "Rolls a die"
}VoiceSeatA seat in a voice channel.
Field Type Meaning urlstringThe media server's address (LiveKit). tokenstringThe token for this channel, valid for a few minutes. iceServersobject[]The STUN and TURN servers for the connection. speakbooleanWhether the bot may send sound there. videobooleanWhether the bot may send video there.
Example {
"url": "wss://voice.example.org",
"token": "eyJhbGciOiJIUzI1NiJ9…",
"iceServers": [
{
"urls": [
"stun:turn.example.org:3478"
]
}
],
"speak": true,
"video": false
}WebhookOne of your webhooks.
Field Type Meaning idstringThe id of the webhook. urlstringIts address. kindsstring[]What it is told about. activebooleanWhether it receives deliveries. After many failures in a row it is switched off. lastStatusintegeror null The HTTP status of the last delivery. lastAtintegeror null When the last delivery was. failuresintegerFailures in a row.
Example {
"id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
"url": "https://example.org/tellmelo-hook",
"kinds": [
"reply",
"mention"
],
"active": true,
"lastStatus": 200,
"lastAt": 1758624000000,
"failures": 0
}WebhookCreatedA new webhook with its secret.
Field Type Meaning idstringThe id of the webhook. secretstringThe secret for the signatures, this once only.
Example {
"id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
"secret": "whsec_3f9a…"
}GroupBotA bot of a group.
Field Type Meaning idstringThe id of the bot account. handlestringIts handle. namestringIts name. descriptionstringWhat it does, in its owner’s words. permissionsstring[]What its role in the group allows.
Example {
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "gardenbot",
"name": "Garden bot",
"description": "Reminds the group of watering days.",
"permissions": [
"send",
"view"
]
}VoiceRoomA voice channel with the people in it.
Field Type Meaning channelstringThe id of the channel. peopleVoicePerson[]Who is in it right now.
Example {
"channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
"people": [
{
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"muted": false,
"deaf": false,
"camera": false,
"screen": true
}
]
}VoicePersonSomeone in a voice channel.
Field Type Meaning idstringThe id of the account. handlestringThe handle. namestringThe display name. mutedbooleanWhether their microphone is off. deafbooleanWhether they hear nothing (their own choice). camerabooleanWhether their camera is on. screenbooleanWhether they share their screen.
Example {
"id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
"handle": "mara",
"name": "Mara 🌻",
"muted": true,
"deaf": false,
"camera": false,
"screen": false
}GiftDropGifts under a post – never with the names of those who claimed them.
Field Type Meaning itemstringWhat a place holds.plan — Plan months (Supporter).sparks — Sparks. quantityintegerHow much each place holds: months or sparks. placesintegerHow many places there are in total. leftintegerHow many are still open. audiencestringWho can claim.all — Everyone.followers — Only followers of the person giving.group — Only members of the post’s group. newAccountsbooleanWhether accounts younger than 7 days can claim too. statusstringWhere things stand.awaiting_payment — Waiting for payment; the post isn’t out yet.open — Places are still up for grabs.closed — Over: all claimed, the payment refunded or the post deleted. claimedbooleanWhether you already have a place yourself (always false on public paths).
Example {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": true
}OwnGiftDropYour gifts under a post, with the post and how they were paid for.
Every field of GiftDrop
Field Type Meaning postIdstringThe post they’re under. fundingstringHow they’re paid for.free — Free.quota — From the quota.payment — Paid. createdAtintegerWhen they were created.
Example {
"item": "plan",
"quantity": 3,
"places": 10,
"left": 4,
"audience": "followers",
"newAccounts": false,
"status": "open",
"claimed": false,
"postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"funding": "quota",
"createdAt": 1758624000000
}QuotaWhat’s in a quota.
Field Type Meaning monthsintegerPlan months still to give away. sparksintegerSparks still to give away. looksQuotaLook[]Looks in stock still to give away (since 2.13).
Example {
"months": 120,
"sparks": 500,
"looks": [
{
"id": "frame-gold",
"name": "Goldring",
"kind": "frame",
"quantity": 25
}
]
}QuotaLookA look in a partner’s stock, with the pieces left (since 2.13).
Field Type Meaning idstringThe look’s ID; pass it as itemId when giving it. namestringThe look’s name. kindstringWhat kind of look it is.frame — Profile frame.background — Cover effect.card — Profile card. quantityintegerHow many pieces are left.
Example {
"id": "frame-gold",
"name": "Goldring",
"kind": "frame",
"quantity": 25
}QuotaGiftA gift from the quota.
Field Type Meaning itemstringWhat was given.plan — Plan months (Supporter).sparks — Sparks.shop — A look from the stock (since 2.13). quantityintegerHow much. itemIdstringor null The look given when item is shop; otherwise null. recipientActorTo whom. createdAtintegerWhen.
Example {
"item": "plan",
"quantity": 3,
"itemId": null,
"recipient": {
"handle": "jon",
"name": "Jon"
},
"createdAt": 1758627600000
}EmbedThe addresses for other websites. They work without a key.
Field Type Meaning pagestringThe player for an <iframe>. filestringThe MP4 file for a player of your own. posterstringThe preview image. codestringThe finished code to embed it.
Example {
"page": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
"file": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/file",
"poster": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/poster",
"code": "<iframe src=\"https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918\" width=\"480\" height=\"300\" title=\"Happy bees\" style=\"border:0;max-width:100%\" loading=\"lazy\" allowfullscreen></iframe>"
}UploadStartedAn upload that has started.
Field Type Meaning uploadstringThe ID of this upload. pieceintegerThe largest a piece may be, in bytes.
Example {
"upload": "e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b",
"piece": 4194304
}UploadPieceA piece that arrived.
Field Type Meaning receivedintegerHow many bytes have arrived. itemMediaItemor null After the last piece the new GIF or video, otherwise null.
Example {
"received": 4194304,
"item": null
}CreatedThe answer of a write that created something.
Field Type Meaning idstringThe id of what was created. scheduledForintegeror null When it appears, if publishing was scheduled (otherwise null). deleteAtintegeror null When it deletes itself, if that was set (otherwise null).
Example {
"id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"scheduledFor": null,
"deleteAt": null
}DropCreatedThe response when a post with gifts was created.
Field Type Meaning idstringThe id of the new post. fundingstringHow the gifts are paid for.free — Free.quota — From the quota.
Example {
"id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
"funding": "quota"
}MadeWhat was just created or changed.
Field Type Meaning idstringThe id; for an invitation link its code.
Example {
"id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}OkThe answer of a write that has nothing to hand back.
Field Type Meaning okbooleanAlways true.
Example {
"ok": true
}The machine-readable description The table behind this page is available as OpenAPI at https://api.tellmelo.com/v2/openapi.json.
https://api.tellmelo.com/v2/openapi.jsonGIFs and videos on other websites What a member shares and also allows on other websites, any website can show: the search with anywhere=true finds it, and its embed has the addresses. If the member takes it back, it disappears there within minutes.
Uploading in pieces Start first, then send the file in pieces. Split a larger file into pieces of piece bytes, with offset at each one’s place. After the last piece you get the finished GIF or video.
curl -X POST -H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/json" \
-d '{"kind":"gif","size":2400000,"name":"Happy bees","shared":true,"anywhere":true}' \
"https://api.tellmelo.com/v2/media/uploads"
→ { "upload": "e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b", "piece": 4194304 }
curl -X PUT -H "Authorization: Bearer tm_key_…" \
-H "Content-Type: application/octet-stream" \
--data-binary @bees.gif \
"https://api.tellmelo.com/v2/media/uploads/e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b?offset=0"
→ { "received": 2400000, "item": { "id": "…", "embed": { … } } }Embedding The player shows the GIF in a loop or the video with controls, below it the name and who shared it. Put the code from embed.code into the page:
<iframe src="https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918" width="480" height="300" title="Happy bees" style="border:0;max-width:100%" loading="lazy" allowfullscreen></iframe>Forums and programs that know oEmbed fetch the code themselves when given the player’s address:
https://tellmelo.com/api/oembed?url=https%3A%2F%2Ftellmelo.com%2Fmedia-embed%2Fb2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918The key belongs on your server, never in a web page’s code. Search and upload through your server; the addresses in embed need no key.
GIF picker for your website With a site key (Developer area → GIF picker for your website ) your website gets a ready-made search: two lines in the page, and a click on the button opens it. The key is public and only works on the addresses you enter for it. The picker only shows what members allowed on other websites.
<script src="https://tellmelo.com/picker.js" data-key="tmsk_…" defer></script>
<button type="button" data-tellmelo-picker>GIF</button>When something is picked, the button fires tellmelo:pick with the item: code to embed it, file, poster, name and author. With data-target="#field" it puts code straight into a text field, with data-kind="video" it searches videos. If you embed the file yourself, show the name of the person who shared it.
document.addEventListener('tellmelo:pick', (event) => {
const { code, file, name, author } = event.detail;
});Sign in with tellmelo Other sites let members sign in with their tellmelo account over OpenID Connect (authorization code with PKCE). The site receives only the username, the confirmed email address and an identifier of its own per member (sub).
You apply for an app under “Developer area → Sign in with tellmelo”. The team checks every app; afterwards you see the client ID there and, for apps with a server, create the client secret, which is shown once.
Everything a library needs is in the discovery document:
https://tellmelo.com/.well-known/openid-configurationSend the member to /oauth/authorize with response_type=code, client_id, redirect_uri (exactly as registered), scope=openid profile email, state, nonce and code_challenge with code_challenge_method=S256. Exchange the code within a minute at /oauth/token: grant_type=authorization_code, code, redirect_uri and code_verifier; apps with a server also send the secret, with Basic authentication or in the form. The ID token (RS256, keys at /oauth/jwks) contains sub, with profile also preferred_username, with email also email and email_verified. The access token is valid for 10 minutes and only reads /oauth/userinfo. https://tellmelo.com/oauth/authorize?response_type=code&client_id=tm_…
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=openid%20profile%20email
&state=…&nonce=…&code_challenge=…&code_challenge_method=S256
curl -u "tm_…:tms_…" https://tellmelo.com/oauth/token \
-d grant_type=authorization_code -d code=… \
-d redirect_uri=https://example.com/callback -d code_verifier=…{
"iss": "https://example.social",
"sub": "Xq3vR0b8yJm1cW4tZ2kPn6sLd9fHa7gE5uTo0iBeVxY",
"aud": "tm_5f2c9e1a7b3d4c6e8f0a1b2c",
"iat": 1760432400,
"exp": 1760433000,
"nonce": "n-0S6_WzA2Mj",
"at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
"preferred_username": "anna",
"email": "anna@example.com",
"email_verified": true
}There are no refresh tokens: tellmelo signs members in and grants no lasting access. If a member removes the site or the team suspends the app, /oauth/userinfo answers 401 at once. prompt=none checks without a page, prompt=consent asks again.
What we expect The same rules apply as everywhere: no harassment, no spam, no content you have no rights to. You are responsible for what your key posts.
Show other members’ GIFs and videos on your website only when they have embed, through those addresses and with the name of whoever shared them. Once something is no longer available, stop showing it. Don’t copy the files into a collection of your own.
