API

Ceci est une traduction. La version allemande est celle qui fait foi. En cas de divergence, c’est le texte allemand qui s’applique. Tu peux changer de langue en bas de page.

Sommaire

Vue d’ensemble

v2 est l’API de tellmelo pour tes propres programmes. Chaque requête porte une clé, chaque réponse est du JSON, et chaque liste se feuillette de la même manière. Ce qui se passe derrière une clé traverse les mêmes règles qu’un clic dans l’application : limites de débit, suspensions, droits retirés et réglages de cette instance valent ici pareillement.

Chaque chemin commence par /api/v2 à l’adresse de cette instance, celle des exemples de cette page.
Requêtes et réponses sont en JSON, en UTF-8. Les noms de champs, les codes et les valeurs sont en anglais et le restent.
Une clé agit en tant que ton compte, jamais au-delà : ce que tu ne peux pas voir dans l’application, aucune clé ne peut le lire.

https://tellmelo.com/api/v2

Démarrage rapide

Crée une clé sous « Réglages → App et données → API » et copie-la. Elle n’est montrée qu’une seule fois.
Interroge la racine avec elle. La réponse dit quelle version tourne, ce que la clé peut faire et combien de requêtes il lui reste cette minute.
Ensuite, chaque chemin fonctionne de la même façon : la clé dans l’en-tête, du JSON en retour, et pour les listes items et next.

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

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

Pour continuer : /me pour ton propre profil, /posts pour ce qui est public, /feed pour ce que l’application te montre.

Ta clé

Il y a exactement une clé par compte, liée à ton identifiant. Elle commence par tm_key_, pour qu’un scanner la reconnaisse là où elle n’a pas sa place. Elle s’affiche une seule fois, au moment où elle est créée ; ensuite il ne reste ici que son empreinte, et personne ne peut te la relire, ni nous ni toi. Qui l’égare en crée une nouvelle ; l’ancienne cesse de valoir à cet instant.

Tu la crées sous « Réglages → App et données → API ». Elle voyage dans l’en-tête de la requête, comme Authorization: Bearer tm_key_… ou comme X-Tellmelo-Key. Pas dans la barre d’adresse, car ce qui s’y trouve finit dans les journaux d’accès, dans l’historique du navigateur et dans le referer de chaque lien.

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

Ou, si c’est plus commode, dans un en-tête à part :

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

Pas dans la barre d’adresse. Ce qui s’y trouve finit dans le journal d’accès de chaque serveur intermédiaire, dans l’historique du navigateur et dans le referer de chaque lien. Une clé n’y a pas sa place.

La même clé charge aussi les images. Chaque url d’une réponse pointe vers /api/media de cette instance ; envoie-y aussi la clé dans l’en-tête, et l’image revient, pour autant que ton compte ait le droit de la voir.

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

Ce qu’une clé a le droit de faire

Une clé porte deux droits, et chaque chemin des tableaux ci-dessous dit lequel il lui faut. Deux et pas cinq : un droit qu’on ne sait pas s’expliquer en une phrase est un droit qu’on coche sans lire. Et la ligne honnête passe entre regarder et changer.

read : regarder. Les publications publiques, les profils, les communautés et les tags, et ton propre compte tel que tu le vois : fil, notifications, conversations, messages.
write : changer. Tout ce qui se passe en ton nom : publier, répondre, voter, envoyer des messages, suivre, rejoindre, bloquer, marquer des notifications comme lues.

Ce qu’aucune clé ne peut

Aucune clé n’atteint les données de ton compte : ni mot de passe, ni adresse e-mail, ni type de compte, ni lieu, ni rôle, ni suppression. Ni les connexions, ni les appareils de notification, ni les clés elles-mêmes : une clé capable d’émettre des clés ne pourrait plus être coupée. Ni l’administration, ni la direction d’une communauté, car dissoudre une communauté ou la transmettre est une décision sur les publications d’autrui. Ce que le mot de passe garde, aucune clé ne le peut : un secret posé dans un script sur la machine d’un autre ne doit pas pouvoir ce que peut la connexion. Prendre un compte coûte toujours la connexion.

Requêtes et réponses

Du JSON partout. Chaque réponse est en application/json, en UTF-8, erreurs comprises. Seules les images arrivent en images.
Ce que tu envoies. Un POST porte ses champs sous forme d’objet JSON dans le corps. Les paramètres de l’adresse complètent ce que le corps ne nomme pas ; si les deux nomment le même champ, le corps l’emporte.
Les dates sont des nombres entiers de millisecondes depuis le 1er janvier 1970, UTC, comme la base de données les garde. Aucun fuseau horaire à mal lire.
Les identifiants sont des chaînes. Ne les découpe pas et ne te fie pas à leur forme ; compare-les uniquement en entier.
Chaque champ est toujours là. Ce qui n’existe pas vaut null, jamais absent ; un nombre est toujours un nombre, une liste toujours une liste, vide s’il le faut.
Les textes sont du texte brut, tels qu’écrits. Les #tags, les @noms et les liens restent tels quels, de même que les émojis propres à l’instance, sous la forme :name: ; leurs images sont listées sous /emojis.
Les images sont des adresses relatives à cette instance, /api/media?id=…. Charge-les avec la même clé dans l’en-tête ; sans elle, la réponse est 401.

Pages

Chaque liste prend limit et cursor et répond par items et next. Tu continues en renvoyant le next de la dernière réponse comme cursor ; quand next est vide, la fin est atteinte. Une page pleine peut tout de même être la dernière, et qui ne s’arrête qu’à une page vide demande une fois de trop. Le curseur est opaque : une place dans une liste, pas un instant. Ne le démonte pas et n’en fabrique pas toi-même ; ce qu’il contient peut changer sans qu’aucun chemin ne change.

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

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

Une page contient 20 entrées sans limit, 50 au plus. Quelques listes ne se feuillettent pas du tout : c’est indiqué à leur chemin, et leur next vaut toujours null.

Seulement ce qui est nouveau

Chaque réponse porte un ETag. Un programme qui redemande sans cesse devrait renvoyer le dernier comme If-None-Match : si rien n’a changé depuis, la réponse est 304 et ne porte pas de corps. C’est la différence entre une liste qui passe sur le fil chaque minute et une qui passe quand il y a quelque chose dedans, pour ta machine autant que pour celle-ci.

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

Deux exceptions, toutes deux voulues : /feed ne porte pas d’ETag, parce que son ordre bouge avec le temps et que chaque réponse est différente ; et une écriture ne répond jamais 304. Deux publications identiques sont deux publications.

Limites

Une clé peut faire 120 requêtes par minute, 600 avec l’abonnement « Organisation », à moins que l’administration ne lui ait fixé un autre nombre. La limite vaut par clé, pas par compte et pas par adresse. Au-delà, la réponse est 429 et rien ne s’est passé : la requête a été refusée, pas exécutée. Attends une minute et renvoie-la ; un programme qui bute régulièrement devrait ralentir plutôt que redemander aussitôt.

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

En plus de la limite de la clé, les écritures comptent dans les mêmes limites que dans l’application : combien de publications, de réponses ou de relations en quelques minutes. Elles aussi répondent 429 avec le code rate_limited.

En-têtes

Les noms sont ceux que toute bibliothèque cliente connaît déjà. Aucun n’est obligatoire, sauf la clé.

Ce que tu envoies

En-tête	Signification
`Authorization`	Porte la clé : `Bearer tm_key_…`. La voie habituelle.
`X-Tellmelo-Key`	La clé, en alternative à `Authorization`, pour les outils qui utilisent cet en-tête pour autre chose.
`Content-Type`	`application/json`, pour une requête avec un corps.
`If-None-Match`	L’`ETag` de la dernière réponse. Si rien n’a changé depuis, la réponse est `304`, sans corps.

Ce qui revient

En-tête	Signification
`ETag`	L’empreinte de cette réponse, marquée comme faible (`W/`). Renvoie-la comme `If-None-Match`.
`X-RateLimit-Limit`	Combien de requêtes cette clé peut faire par minute.
`X-RateLimit-Remaining`	Combien il en reste dans la minute en cours.
`X-RateLimit-Reset`	Quand la minute suivante commence, en secondes depuis 1970, UTC.
`X-Tellmelo-Scope`	Ce que cette clé peut faire : `read` ou `read write`.
`Retry-After`	Avec un `429` : combien de secondes attendre avant de redemander.
`WWW-Authenticate`	Avec un `401` pour une clé absente : `Bearer`, la façon dont une clé est attendue.
`Cache-Control`	`no-store` : aucun proxy intermédiaire ne peut garder une réponse, car elle dépend de la clé qui demande. Ton propre programme peut quand même la vérifier avec l’`ETag`.

Quand quelque chose ne marche pas

Les erreurs arrivent en JSON avec deux champs : un code anglais fixe dans error, que ton programme peut comparer, et une phrase dans message pour la personne devant, avec le code d’état qui va avec. Le code ne change pas ; la phrase peut changer, et elle peut changer dans chaque langue : un programme qui compare la phrase casse un jour que personne n’a annoncé.

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

Certaines erreurs apportent un champ de plus : docs avec un 401 pour une clé absente, limit avec un 429.

Statut	Code	Signification
`400`	`bad_request`	La requête est illisible, un champ obligatoire manque, ou une valeur ne fait pas partie de celles permises. Le `message` dit laquelle.
`401`	`key_missing`	Pas de clé dans l’en-tête.
`401`	`key_invalid`	La clé n’est pas valable : mal recopiée, remplacée par une nouvelle, ou son compte est suspendu. Lequel des trois, ce n’est volontairement pas dit.
`401`	`unauthorized`	Refusé comme non connecté, pour une autre raison que la clé. Rare, et une raison de regarder le compte derrière la clé.
`403`	`scope_missing`	Il manque à la clé le droit dont ce chemin a besoin : le plus souvent `write` pour une clé qui peut seulement lire.
`403`	`account_data_locked`	Cela touche aux données de ton compte, qu’aucune clé n’atteint : mot de passe, adresse e-mail, suppression et ce genre de choses.
`403`	`forbidden`	Ton compte n’a pas le droit de faire cela : le même refus que dans l’application, par exemple un droit retiré ou un blocage.
`404`	`unknown_path`	Ce chemin n’existe pas, ou pas avec cette méthode.
`404`	`not_found`	Le chemin existe, mais pas ce qu’il désigne, ou tu n’as pas le droit de le voir. Les deux ne sont pas distingués.
`409`	`conflict`	Cela entre en conflit avec ce qui existe déjà, par exemple un nom déjà pris.
`413`	`too_large`	Trop grand : un texte ou une requête au-delà de ce que cette instance accepte.
`422`	`unprocessable`	Lisible, mais pas possible sous cette forme.
`429`	`rate_limited`	Trop de requêtes. Rien n’a été fait ; attends et renvoie-la.
`500`	`internal_error`	Quelque chose a échoué de notre côté, pas du tien. C’est consigné en entier sur le serveur.

Versions

La version est dans le chemin. Tant qu’il y est écrit v2, ces chemins et leurs champs restent tels quels ; ce qui s’ajoute vient à côté.

Les ajouts font monter le second chiffre : 2.1 a apporté /emojis et le marquage d’une conversation comme lue. 2.4 a retiré le champ contentWarning, car les avertissements de contenu n’existent plus. 2.5 a retiré le champ alt des images, car les descriptions d’images n’existent plus. 2.6 ajoute le type de notification team pour le nouveau travail de l’équipe. Chaque chemin indique depuis quelle version il existe, et la racine dit quelle version tourne.

Points d’accès

Tous les chemins d’un coup d’œil, puis chacun en détail : ce qu’il prend, un exemple de requête et ce qui revient.

Chemin	Droit	À quoi
L’entrée
GET`/api/v2`	`read`	L’entrée : quelle version parle cette API et comment s’appelle cette instance.
Publications
GET`/api/v2/posts`	`read`	Les publications publiques, les plus récentes d’abord.
GET`/api/v2/posts/{id}`	`read`	Une seule publication, par son `id`.
POST`/api/v2/posts`	`write`	Publier une publication.
DELETE`/api/v2/posts/{id}`	`write`	Retirer une de tes publications.
Réponses
GET`/api/v2/posts/{id}/replies`	`read`	Les réponses à une publication, telles que tu les vois : ce qu’a écrit un compte bloqué reste dehors.
POST`/api/v2/posts/{id}/replies`	`write`	Répondre à une publication.
Sondages
POST`/api/v2/posts/{id}/vote`	`write`	Participer à un sondage.
Profils
GET`/api/v2/profiles/{handle}`	`read`	Un profil, par son identifiant court.
GET`/api/v2/profiles/{handle}/posts`	`read`	Les publications publiques d’un profil, les plus récentes d’abord.
Communautés
GET`/api/v2/communities`	`read`	Les communautés ouvertes de cette instance.
GET`/api/v2/communities/{id}`	`read`	Une seule communauté, par son `id`.
GET`/api/v2/communities/{id}/posts`	`read`	Les publications publiques d’une communauté, les plus récentes d’abord.
Découvrir
GET`/api/v2/tags`	`read`	Les tags qui tournent en ce moment.
GET`/api/v2/search`	`read`	Une recherche sur les publications, les noms, les identifiants courts et les tags.
GET`/api/v2/emojis`	`read`	Les émojis propres à l’instance, avec l’adresse de leurs images.
Ton compte
GET`/api/v2/me`	`read`	Ton propre profil, avec l’`id` que les autres chemins attendent.
GET`/api/v2/feed`	`read`	Ton propre fil, tel que l’application le compose.
Notifications
GET`/api/v2/notifications`	`read`	Tes propres notifications, les plus récentes d’abord, feuilletables, pour qu’un programme rattrape ce qu’il a manqué.
POST`/api/v2/notifications/read`	`write`	Marquer tes notifications comme lues.
Messages
GET`/api/v2/conversations`	`read`	Ta boîte : une ligne par conversation, la plus récente d’abord.
GET`/api/v2/conversations/{with}/messages`	`read`	Les messages d’une conversation, les plus récents d’abord.
POST`/api/v2/conversations/{with}/messages`	`write`	Envoyer un message dans une conversation.
POST`/api/v2/conversations/{with}/read`	`write`	Marquer tous les messages d’une conversation comme lus.
Relations
POST`/api/v2/relations`	`write`	Aimer, garder, partager, suivre, rejoindre, bloquer, masquer, selon `kind`.

L’entrée

La première requête de tout programme : la clé fonctionne-t-elle, et que peut-elle faire ?

GET`/api/v2`

L’entrée : quelle version parle cette API et comment s’appelle cette instance.

Droit read
avec ETag
depuis v2.0

Sans barre oblique à la fin : /api/v2/ redirige vers /api/v2 avec 308, et tous les programmes ne suivent pas.

Exemple de requête

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

Réponse

Répond avec un Service.

Exemple

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

Statuts possibles : 200304401429

Publications

Lire les publications publiques, publier les tiennes et les retirer.

GET`/api/v2/posts`

Les publications publiques, les plus récentes d’abord.

Droit read
paginé
avec ETag
depuis v2.0

Sur les chemins publics, les réactions ne sont pas comptées : counts.likes et counts.reposts valent 0 et pinned vaut false (une coupe, pas une mesure).

Les publications d’une communauté ne s’atteignent pas ici, ni dans la liste ni par leur id. Elles se lisent sous /communities/{id}/posts.

Paramètres

Nom	Type	Signification
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.
`cursor`dans l’adresse	`string`facultatif	Où cela reprend : le `next` de la réponse précédente. Sans lui, depuis le haut.

Exemple de requête

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

Réponse

Répond avec une page de Post, sous forme de `items` et `next`.

Exemple

{
  "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"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Statuts possibles : 200304401429

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

Une seule publication, par son id.

Droit read
avec ETag
depuis v2.0

Sur les chemins publics, les réactions ne sont pas comptées : counts.likes et counts.reposts valent 0 et pinned vaut false (une coupe, pas une mesure).

Les publications d’une communauté ne s’atteignent pas ici, ni dans la liste ni par leur id. Elles se lisent sous /communities/{id}/posts.

Paramètres

Nom	Type	Signification
`id`dans le chemin	`string`obligatoire	L’`id` d’une publication.

Exemple de requête

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

Réponse

Répond avec un Post.

Exemple

{
  "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"
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": 1758710400000,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "createdAt": 1758624000000
}

Statuts possibles : 200304400401404429

POST`/api/v2/posts`

Publier une publication.

Droit write
depuis v2.0

Une publication a besoin d’un texte ou d’un sondage. Sa longueur, le nombre de réponses d’un sondage et combien de publications en combien de temps sont fixés par cette instance ; au-delà, la réponse est 400 ou 429, avec un message qui dit lequel.

On ne peut pas encore joindre d’images via l’API, seulement dans l’application.

Paramètres

Nom	Type	Signification
`text`dans le corps	`string`facultatif	Le texte lui-même : de la publication, de la réponse ou du message.
`community`dans le corps	`string`facultatif	L’`id` de la communauté où va la publication. Sans elle, en dehors de toute communauté.
`quotes`dans le corps	`string`facultatif	L’`id` de la publication que celle-ci cite.
`poll`dans le corps	`string[]`facultatif	Les options de réponse d’un sondage, comme une liste de textes. Combien sont permises, l’instance le fixe.

Exemple de requête

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

Réponse

Répond avec un Created.

Exemple

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

Statuts possibles : 200400401403429

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

Retirer une de tes publications.

Droit write
depuis v2.0

Paramètres

Nom	Type	Signification
`id`dans le chemin	`string`obligatoire	L’`id` d’une publication.

Exemple de requête

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

Réponse

Répond avec un Ok.

Exemple

{
  "ok": true
}

Statuts possibles : 200400401403404429

Réponses

La conversation sous une publication : lue comme une liste que parentId transforme en arbre, écrite en répondant à la publication ou à une réponse.

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

Les réponses à une publication, telles que tu les vois : ce qu’a écrit un compte bloqué reste dehors.

Droit read
paginé
avec ETag
depuis v2.0

La liste est plate et dans l’ordre d’écriture ; parentId en fait un arbre. Une page contient des fils entiers, une réponse n’arrive donc jamais sans celle à laquelle elle répond. Ce qu’a écrit un compte que tu as bloqué, ou qui t’a bloqué, est laissé de côté. Deux clés peuvent voir des listes différentes.

Paramètres

Nom	Type	Signification
`id`dans le chemin	`string`obligatoire	L’`id` d’une publication.
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.
`cursor`dans l’adresse	`string`facultatif	Où cela reprend : le `next` de la réponse précédente. Sans lui, depuis le haut.

Exemple de requête

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

Réponse

Répond avec une page de Reply, sous forme de `items` et `next`.

Exemple

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

Statuts possibles : 200304400401404429

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

Répondre à une publication.

Droit write
depuis v2.0

Sous une publication en mode lent, chaque personne peut répondre une fois toutes les 10 minutes ; une réponse de plus reçoit 429 avec le délai dans le message. Le mode ne s’applique ni à l’auteur ni aux comptes qu’il suit.

Paramètres

Nom	Type	Signification
`id`dans le chemin	`string`obligatoire	L’`id` d’une publication.
`text`dans le corps	`string`obligatoire	Le texte lui-même : de la publication, de la réponse ou du message.
`parentId`dans le corps	`string`facultatif	L’`id` de la réponse à laquelle celle-ci répond. Sans elle, directement à la publication.

Exemple de requête

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

Réponse

Répond avec un Created.

Exemple

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

Statuts possibles : 200400401403404429

Sondages

Un sondage est une publication dont poll est renseigné. Voter a son propre chemin.

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

Participer à un sondage.

Droit write
depuis v2.0

Les voix par réponse valent null tant que le résultat est retenu : avant ton propre vote, pendant que le sondage court. total est toujours là.

Paramètres

Nom	Type	Signification
`id`dans le chemin	`string`obligatoire	L’`id` d’une publication.
`option`dans le corps	`integer`obligatoire	Quelle réponse, comptée à partir de 0. Une par appel : un sondage à plusieurs réponses se vote en appelant plusieurs fois.
`retract`dans le corps	`boolean`facultatif	Si cette voix est retirée : `true` l’annule.

Exemple de requête

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

Réponse

Répond avec un Ok.

Exemple

{
  "ok": true
}

Statuts possibles : 200400401403404429

Profils

Les profils publics par leur nom court, et ce qu’ils ont publié.

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

Un profil, par son identifiant court.

Droit read
avec ETag
depuis v2.0

Paramètres

Nom	Type	Signification
`handle`dans le chemin	`string`obligatoire	L’identifiant court d’un profil.

Exemple de requête

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

Réponse

Répond avec un Profile.

Exemple

{
  "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
}

Statuts possibles : 200304400401404429

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

Les publications publiques d’un profil, les plus récentes d’abord.

Droit read
paginé
avec ETag
depuis v2.0

Sur les chemins publics, les réactions ne sont pas comptées : counts.likes et counts.reposts valent 0 et pinned vaut false (une coupe, pas une mesure).

Les publications d’une communauté ne s’atteignent pas ici, ni dans la liste ni par leur id. Elles se lisent sous /communities/{id}/posts.

Paramètres

Nom	Type	Signification
`handle`dans le chemin	`string`obligatoire	L’identifiant court d’un profil.
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.
`cursor`dans l’adresse	`string`facultatif	Où cela reprend : le `next` de la réponse précédente. Sans lui, depuis le haut.

Exemple de requête

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

Réponse

Répond avec une page de Post, sous forme de `items` et `next`.

Exemple

{
  "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"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Statuts possibles : 200304400401404429

Communautés

Les communautés ouvertes de cette instance et leurs publications. Les internes et les cachées ne sont pas accessibles avec une clé.

GET`/api/v2/communities`

Les communautés ouvertes de cette instance.

Droit read
avec ETag
depuis v2.0

Triée par nombre de membres, pas par date, cette liste ne se feuillette donc pas, et next vaut toujours null.

Paramètres

Nom	Type	Signification
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.

Exemple de requête

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

Réponse

Répond avec une page de Community, sous forme de `items` et `next`.

Exemple

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

Statuts possibles : 200304401429

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

Une seule communauté, par son id.

Droit read
avec ETag
depuis v2.0

Paramètres

Nom	Type	Signification
`id`dans le chemin	`string`obligatoire	L’`id` d’une communauté.

Exemple de requête

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

Réponse

Répond avec un Community.

Exemple

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

Statuts possibles : 200304400401404429

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

Les publications publiques d’une communauté, les plus récentes d’abord.

Droit read
paginé
avec ETag
depuis v2.0

Sur les chemins publics, les réactions ne sont pas comptées : counts.likes et counts.reposts valent 0 et pinned vaut false (une coupe, pas une mesure).

Paramètres

Nom	Type	Signification
`id`dans le chemin	`string`obligatoire	L’`id` d’une communauté.
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.
`cursor`dans l’adresse	`string`facultatif	Où cela reprend : le `next` de la réponse précédente. Sans lui, depuis le haut.

Exemple de requête

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

Réponse

Répond avec une page de Post, sous forme de `items` et `next`.

Exemple

{
  "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"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Statuts possibles : 200304400401404429

Découvrir

Ce dont on parle en ce moment, une recherche dans les publications, les profils et les tags, et les émojis propres à l’instance.

GET`/api/v2/tags`

Les tags qui tournent en ce moment.

Droit read
avec ETag
depuis v2.0

Les tags du moment, les plus publiés d’abord. Pas de pagination : limit ne fait que raccourcir la liste.

Paramètres

Nom	Type	Signification
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.

Exemple de requête

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

Réponse

Répond avec une page de Tag, sous forme de `items` et `next`.

Exemple

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

Statuts possibles : 200304401429

GET`/api/v2/search`

Une recherche sur les publications, les noms, les identifiants courts et les tags.

Droit read
avec ETag
depuis v2.0

Ne cherche que dans ce qui est public : publications hors communautés, profils et tags. limit compte par type : 20 peut ramener jusqu’à 20 publications, 20 profils et 20 tags.

Paramètres

Nom	Type	Signification
`q`dans l’adresse	`string`obligatoire	Les mots cherchés.
`type`dans l’adresse	`string`facultatif	Quel genre de résultat. Sans lui, tous les genres.`allpostsprofilestags`
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.

Exemple de requête

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

Réponse

Répond avec un SearchResult.

Exemple

{
  "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"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

Statuts possibles : 200304400401429

GET`/api/v2/emojis`

Les émojis propres à l’instance, avec l’adresse de leurs images.

Droit read
avec ETag
depuis v2.1

Dans les textes, un émoji de cette instance apparaît sous la forme :name:. Remplace-le par l’image de cette liste ; un nom qui n’y figure pas reste du texte : il a été supprimé ou n’a jamais existé.

Exemple de requête

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

Réponse

Répond avec une page de Emoji, sous forme de `items` et `next`.

Exemple

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

Statuts possibles : 200304401429

Ton compte

Ton propre profil et ton fil, composés comme l’application le fait pour toi.

GET`/api/v2/me`

Ton propre profil, avec l’id que les autres chemins attendent.

Droit read
avec ETag
depuis v2.0

Exemple de requête

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

Réponse

Répond avec un Profile.

Exemple

{
  "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
}

Statuts possibles : 200304401429

GET`/api/v2/feed`

Ton propre fil, tel que l’application le compose.

Droit read
paginé
depuis v2.0

Pas d’ETag ici : l’ordre bouge avec le temps, chaque réponse est donc différente. Une liste commencée reste pourtant la même jusqu’au bout : next porte le moment où elle a commencé.

Paramètres

Nom	Type	Signification
`tab`dans l’adresse	`string`facultatif	Quel fil : `for-you`, `following`, `latest` ou `bookmarks`. `latest` par défaut.`for-youfollowinglatestbookmarks`
`tag`dans l’adresse	`string`facultatif	Seulement les publications portant ce tag. Sans lui, aucun filtre.
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.
`cursor`dans l’adresse	`string`facultatif	Où cela reprend : le `next` de la réponse précédente. Sans lui, depuis le haut.

Exemple de requête

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

Réponse

Répond avec une page de Post, sous forme de `items` et `next`.

Exemple

{
  "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"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

Statuts possibles : 200400401429

Notifications

Ce qui s’est passé autour de ton compte, lisible page par page, pour qu’un programme puisse rattraper ce qu’il a manqué.

GET`/api/v2/notifications`

Tes propres notifications, les plus récentes d’abord, feuilletables, pour qu’un programme rattrape ce qu’il a manqué.

Droit read
paginé
avec ETag
depuis v2.0

Lire ne marque rien comme lu ; c’est POST /notifications/read qui le fait. Plusieurs évènements du même type sur la même publication sont regroupés en une ligne, et more dit combien.

Paramètres

Nom	Type	Signification
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.
`cursor`dans l’adresse	`string`facultatif	Où cela reprend : le `next` de la réponse précédente. Sans lui, depuis le haut.

Exemple de requête

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

Réponse

Répond avec une page de Notification, sous forme de `items` et `next`.

Exemple

{
  "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"
}

Statuts possibles : 200304401429

POST`/api/v2/notifications/read`

Marquer tes notifications comme lues.

Droit write
depuis v2.0

Exemple de requête

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

Réponse

Répond avec un Ok.

Exemple

{
  "ok": true
}

Statuts possibles : 200401403429

Messages

Ta boîte de réception et tes conversations. Une conversation n’a pas d’identifiant propre ; elle porte le nom de l’autre compte.

GET`/api/v2/conversations`

Ta boîte : une ligne par conversation, la plus récente d’abord.

Droit read
paginé
avec ETag
depuis v2.0

Paramètres

Nom	Type	Signification
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.
`cursor`dans l’adresse	`string`facultatif	Où cela reprend : le `next` de la réponse précédente. Sans lui, depuis le haut.

Exemple de requête

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

Réponse

Répond avec une page de Conversation, sous forme de `items` et `next`.

Exemple

{
  "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"
}

Statuts possibles : 200304401429

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

Les messages d’une conversation, les plus récents d’abord.

Droit read
paginé
avec ETag
depuis v2.0

Lire ne marque rien comme lu : un programme qui récupère en arrière-plan n’a rien montré à personne. C’est POST /conversations/{with}/read qui le fait.

Paramètres

Nom	Type	Signification
`with`dans le chemin	`string`obligatoire	L’`id` du compte avec qui tu parles. Une conversation n’a pas d’`id` à elle : c’est l’autre compte, la même valeur que la boîte appelle `with`.
`limit`dans l’adresse	`integer`facultatif	Combien d’entrées tient une page : 20 par défaut, 50 au plus.
`cursor`dans l’adresse	`string`facultatif	Où cela reprend : le `next` de la réponse précédente. Sans lui, depuis le haut.

Exemple de requête

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

Réponse

Répond avec une page de Message, sous forme de `items` et `next`.

Exemple

{
  "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"
}

Statuts possibles : 200304400401404429

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

Envoyer un message dans une conversation.

Droit write
depuis v2.0

Les mêmes règles que dans l’application s’appliquent : on ne peut pas écrire à qui t’a bloqué, et les réglages de l’autre personne comptent. La réponse dit alors pourquoi.

On ne peut pas encore joindre d’images via l’API, seulement dans l’application.

Paramètres

Nom	Type	Signification
`with`dans le chemin	`string`obligatoire	L’`id` du compte avec qui tu parles. Une conversation n’a pas d’`id` à elle : c’est l’autre compte, la même valeur que la boîte appelle `with`.
`text`dans le corps	`string`obligatoire	Le texte lui-même : de la publication, de la réponse ou du message.
`replyTo`dans le corps	`string`facultatif	L’`id` d’un message précédent de cette conversation auquel celui-ci répond. Depuis 2.2.

Exemple de requête

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

Réponse

Répond avec un Ok.

Exemple

{
  "ok": true
}

Statuts possibles : 200400401403404429

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

Marquer tous les messages d’une conversation comme lus.

Droit write
depuis v2.1

Paramètres

Nom	Type	Signification
`with`dans le chemin	`string`obligatoire	L’`id` du compte avec qui tu parles. Une conversation n’a pas d’`id` à elle : c’est l’autre compte, la même valeur que la boîte appelle `with`.

Exemple de requête

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

Réponse

Répond avec un Ok.

Exemple

{
  "ok": true
}

Statuts possibles : 200400401403404429

Relations

Aimer, enregistrer, republier, suivre, rejoindre et bloquer : un seul chemin pour tout, établi et retiré avec active.

POST`/api/v2/relations`

Aimer, garder, partager, suivre, rejoindre, bloquer, masquer, selon kind.

Droit write
depuis v2.0

target est une publication pour like, save et repost, une communauté pour join, un compte pour follow, block et mute, toujours par son id. active: false retire la relation. Personne ne peut suivre par-dessus un blocage, dans aucun sens. Seule la personne qui masque voit le masquage.

Paramètres

Nom	Type	Signification
`kind`dans le corps	`string`obligatoire	Quelle relation : `like`, `save`, `repost`, `follow`, `join`, `block` ou `mute` (depuis 2.2).`likesaverepostfollowjoinblockmute`
`target`dans le corps	`string`obligatoire	Ce que la relation vise, par son `id` : une publication, un profil ou une communauté, selon `kind`.
`active`dans le corps	`boolean`facultatif	Si la relation doit tenir : `true` la pose, `false` la retire.

Exemple de requête

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

Réponse

Répond avec un Ok.

Exemple

{
  "ok": true
}

Statuts possibles : 200400401403429

Objets

Tout ce qu’une réponse peut contenir, champ par champ. Chaque champ est toujours présent ; les types sont des types JSON, et [] signifie une liste.

`Service`

La réponse de la racine : qui répond, et ce que cette clé peut faire.

Champ	Type	Signification
`name`	`string`	Toujours `tellmelo`.
`version`	`string`	La version de l’API, par exemple `2.1`.
`scope`	`string`	Ce que cette clé peut faire : `read` ou `read write`.
`rateLimit`	`RateLimit`	Le quota de cette clé.
`docs`	`string`	Où se trouve cette documentation, comme chemin sur cette instance.
`spec`	`string`	Où se trouve la description lisible par machine.

Exemple

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

`RateLimit`

Le quota de cette clé dans la minute en cours.

Champ	Type	Signification
`limit`	`integer`	Requêtes par minute.
`remaining`	`integer`	Combien il en reste dans cette minute.

Exemple

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

`Post`

Une publication : la même forme partout, qu’elle soit publique, de ton fil ou d’une recherche.

Champ	Type	Signification
`id`	`string`	L’identifiant de la publication.
`text`	`string`ou null	Le texte tel qu’écrit (`null` pour une publication qui n’est qu’un sondage ou que des images).
`kind`	`string`	Ce qu’est la publication. `post` — Une publication avec du texte, des images ou une citation. `poll` — Une publication avec un sondage.
`author`	`ProfileBrief`	Qui l’a écrite.
`community`	`CommunityBrief`ou null	La communauté où elle a été écrite (`null` hors de toute communauté).
`media`	`Media[]`	Ses images, dans l’ordre ; vide s’il n’y en a pas.
`poll`	`Poll`ou null	Le sondage (`null` s’il n’y en a pas).
`quotes`	`string`ou null	L’identifiant de la publication que celle-ci cite.
`continues`	`string`ou null	L’identifiant de la publication que celle-ci prolonge, comme complément.
`counts`	`Counts`	Réponses, mentions J’aime et republications.
`pinned`	`boolean`	Si elle est épinglée en haut du profil de son auteur.
`createdAt`	`integer`	Quand elle a été écrite.

Exemple

{
  "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"
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": 1758710400000,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "createdAt": 1758624000000
}

`Reply`

Une réponse sous une publication : une publication avec deux champs de plus.

Chaque champ de Post, et en plus :

Champ	Type	Signification
`postId`	`string`	La publication à laquelle toute la conversation est rattachée.
`parentId`	`string`ou null	La réponse à laquelle celle-ci répond (`null` si elle répond directement à la publication).

Exemple

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

`Counts`

Combien de réponses, de mentions J’aime et de republications a une publication.

Champ	Type	Signification
`replies`	`integer`	Les réponses, tous niveaux confondus.
`likes`	`integer`	Les mentions J’aime.
`reposts`	`integer`	Les republications.

Exemple

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

`Media`

Une image d’une publication ou d’un message.

Champ	Type	Signification
`url`	`string`	L’adresse de l’image, relative à cette instance. Charge-la avec la clé dans l’en-tête.

Exemple

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

`Poll`

Le sondage d’une publication.

Champ	Type	Signification
`options`	`PollOption[]`	Les réponses, dans l’ordre. `option` d’un vote compte à partir de 0.
`total`	`integer`	Combien de voix il y a au total : toujours, même quand la répartition est retenue.
`multiple`	`boolean`	Si l’on peut choisir plus d’une réponse.
`endsAt`	`integer`ou null	Quand le sondage se termine (`null` s’il n’a pas de fin).
`running`	`boolean`	Si l’on peut encore voter.
`resultsVisible`	`boolean`	Si les voix par réponse sont montrées (voir `votes`).
`myVotes`	`integer[]`	Les réponses que tu as choisies, comptées à partir de 0.

Exemple

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

`PollOption`

Une réponse d’un sondage.

Champ	Type	Signification
`text`	`string`	La réponse.
`votes`	`integer`ou null	Ses voix (`null` tant que le résultat est retenu).

Exemple

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

`ProfileBrief`

Un profil tel qu’il apparaît dans d’autres objets : comme auteur, dans une recherche.

Champ	Type	Signification
`id`	`string`	L’identifiant du compte : ce qu’attendent `/relations` et `/conversations/{with}`.
`handle`	`string`	Le nom court, sans `@`. Il fait partie de l’adresse du profil et ne peut pas contenir d’émojis.
`name`	`string`	Le nom affiché. Il peut contenir des émojis, y compris `:name:`.
`verified`	`boolean`	Si le compte est vérifié.
`accountKind`	`string`	Quel genre de compte c’est. `person` — Une personne. `business` — Une entreprise. `association` — Une association. `automated` — Un compte automatisé, comme un bot.

Exemple

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

`Profile`

Un profil seul, avec sa description et ses abonnés.

Chaque champ de ProfileBrief, et en plus :

Champ	Type	Signification
`about`	`string`ou null	La description (`null` s’il n’y en a pas).
`website`	`string`ou null	Le site web du profil (`null` s’il n’y en a pas). Depuis 2.3.
`websiteVerified`	`boolean`	Si le site renvoie vers ce profil avec `rel=me`, vérifié au cours de la dernière semaine. Depuis 2.3.
`followers`	`integer`	Combien de comptes le suivent.
`createdAt`	`integer`	Quand le compte a été créé.

Exemple

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

`CommunityBrief`

La communauté dans laquelle une publication a été écrite.

Champ	Type	Signification
`id`	`string`	L’identifiant de la communauté.
`name`	`string`ou null	Son nom.

Exemple

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

`Community`

Une communauté de cette instance.

Champ	Type	Signification
`id`	`string`	L’identifiant de la communauté.
`name`	`string`	Son nom.
`description`	`string`ou null	La description (`null` s’il n’y en a pas).
`tags`	`string[]`	Les sujets dont elle traite.
`members`	`integer`	Combien de membres elle compte.
`joinPolicy`	`string`	Comment on y entre. `open` — Tout le monde peut rejoindre. `application` — Rejoindre demande une candidature que la communauté accepte. `invite` — Seulement sur invitation.
`visibility`	`string`	Qui peut la voir. Via une clé toujours `open` : les autres ne sont pas accessibles. `open` — Visible par tout le monde.

Exemple

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

`Tag`

Un tag et combien de publications le portent.

Champ	Type	Signification
`tag`	`string`	Le tag, sans `#`.
`posts`	`integer`	Combien de publications récentes le portent.

Exemple

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

`SearchResult`

Ce qu’une recherche trouve : trois listes, chacune peut-être vide, jamais absente.

Champ	Type	Signification
`posts`	`Post[]`	Les publications trouvées, les plus récentes d’abord.
`profiles`	`ProfileBrief[]`	Les profils trouvés, par nom court.
`tags`	`Tag[]`	Les tags trouvés, les plus utilisés d’abord.

Exemple

{
  "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"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

`Emoji`

Un émoji de cette instance.

Champ	Type	Signification
`name`	`string`	Le nom, tel qu’il figure entre les deux-points.
`url`	`string`	L’adresse de l’image, relative à cette instance.

Exemple

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

`Notification`

Une notification. Une ligne peut regrouper plusieurs évènements du même type.

Champ	Type	Signification
`id`	`string`	L’identifiant de la notification.
`kind`	`string`	Ce qui s’est passé. `reply` — Quelqu’un t’a répondu. `like` — Quelqu’un aime ta publication. `repost` — Quelqu’un a republié ta publication. `follow` — Quelqu’un te suit. `mention` — Quelqu’un t’a mentionné. `group_mention` — Quelqu’un a mentionné un groupe que tu diriges ; `text` est son nom. `message` — Quelqu’un t’a écrit un message. `scheduled` — Une de tes publications programmées est parue. `reminder` — Un rappel sur une publication enregistrée est arrivé. `report` — Ce qu’est devenu un signalement que tu as envoyé. `moderation` — Une décision sur ton compte : un avertissement, une restriction, un recours. `team` — Nouveau travail pour l’équipe, uniquement pour propriétaires, admins et modérateurs : signalements, recours, liens soumis, demandes, demandes de vérification et résiliations.
`text`	`string`ou null	Seulement pour les signalements et la modération : le texte qui l’accompagne. Sinon `null` : la phrase d’une notification, c’est ton programme qui la construit.
`actor`	`Actor`	Qui l’a fait.
`postId`	`string`ou null	La publication concernée (`null` s’il n’y en a pas).
`read`	`boolean`	Si elle a été marquée comme lue.
`more`	`integer`	Pour combien d’autres évènements cette ligne compte, au-delà de celui qui est nommé.
`createdAt`	`integer`	Quand c’est arrivé la première fois.
`updatedAt`	`integer`	Quand elle a regroupé un évènement pour la dernière fois. La liste est triée ainsi.

Exemple

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

`Actor`

Qui a déclenché une notification.

Champ	Type	Signification
`handle`	`string`	Le nom court.
`name`	`string`	Le nom affiché.

Exemple

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

`Conversation`

Une ligne de ta boîte de réception.

Champ	Type	Signification
`with`	`string`	L’identifiant de l’autre compte : ce qu’attend `/conversations/{with}/messages`.
`handle`	`string`	Son nom court.
`name`	`string`	Son nom affiché.
`excerpt`	`string`ou null	Le début du dernier message (`null` s’il n’a pas de texte).
`truncated`	`boolean`	Si l’extrait a été raccourci.
`fromMe`	`boolean`	Si le dernier message est de toi.
`lastMessageId`	`string`	L’identifiant du dernier message.
`unread`	`integer`	Combien de ses messages tu n’as pas encore lus.
`updatedAt`	`integer`	Quand le dernier message a été écrit.

Exemple

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

`Message`

Un message dans une conversation.

Champ	Type	Signification
`id`	`string`	L’identifiant du message.
`text`	`string`ou null	Le texte (`null` pour un message qui n’est fait que d’images).
`from`	`string`	L’identifiant du compte qui l’a écrit.
`to`	`string`	L’identifiant du compte à qui il a été écrit.
`read`	`boolean`	Si le destinataire l’a lu.
`media`	`Media[]`	Ses images ; vide s’il n’y en a pas.
`replyTo`	`string`ou null	L’`id` du message auquel celui-ci répond (`null` s’il ne répond à aucun). Depuis 2.2.
`createdAt`	`integer`	Quand il a été envoyé.

Exemple

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

`Created`

La réponse d’une écriture qui a créé quelque chose.

Champ	Type	Signification
`id`	`string`	L’identifiant de ce qui a été créé.
`scheduledFor`	`integer`ou null	Quand cela apparaît, si la publication a été programmée (sinon `null`).
`deleteAt`	`integer`ou null	Quand cela se supprime tout seul, si c’était réglé (sinon `null`).

Exemple

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

`Ok`

La réponse d’une écriture qui n’a rien à rendre.

Champ	Type	Signification
`ok`	`boolean`	Toujours `true`.

Exemple

{
  "ok": true
}

La description lisible par une machine

Le même tableau à partir duquel cette page est bâtie est servi sous /api/v2/openapi.json : chemins, paramètres, droits et les formes qui reviennent. Un générateur de clients peut le lire, et il ne peut pas s’écarter de l’API, car la page, le routeur et la description viennent d’une seule liste.

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

Ce qu’est devenue v1

v1 est supprimée. Les anciens chemins sous /api/v1/ répondent 410 et indiquent dans le corps où aller. Pas de redirection, car v2 répond sous une autre forme, et un programme qui la suivrait recevrait un 200 qu’il ne sait pas lire. Il n’y avait alors pas encore de comptes publics, donc personne avec un programme dessus ; la retirer plus tard aurait voulu dire ne jamais la retirer.

Ce que nous attendons

Les mêmes principes que partout ailleurs : pas de harcèlement, pas de spam, pas de contenus d’autrui sans en avoir le droit. Un programme n’excuse rien : tu réponds de ce que ta clé écrit.

API

Vue d’ensemble

Démarrage rapide

Ta clé

Ce qu’une clé a le droit de faire

Ce qu’aucune clé ne peut

Requêtes et réponses

Pages

Seulement ce qui est nouveau

Limites

En-têtes

Ce que tu envoies

Ce qui revient

Quand quelque chose ne marche pas

Versions

Points d’accès

L’entrée

GET/api/v2

Exemple de requête

Réponse

Publications

GET/api/v2/posts

Paramètres

Exemple de requête

Réponse

GET/api/v2/posts/{id}

Paramètres

Exemple de requête

Réponse

POST/api/v2/posts

Paramètres

Exemple de requête

Réponse

DELETE/api/v2/posts/{id}

Paramètres

Exemple de requête

Réponse

Réponses

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

Paramètres

Exemple de requête

Réponse

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

Paramètres

Exemple de requête

Réponse

Sondages

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

Paramètres

Exemple de requête

Réponse

Profils

GET/api/v2/profiles/{handle}

Paramètres

Exemple de requête

Réponse

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

Paramètres

Exemple de requête

Réponse

Communautés

GET/api/v2/communities

Paramètres

Exemple de requête

Réponse

GET/api/v2/communities/{id}

Paramètres

Exemple de requête

Réponse

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

Paramètres

Exemple de requête

Réponse

Découvrir

GET/api/v2/tags

Paramètres

Exemple de requête

Réponse

GET/api/v2/search

Paramètres

GET`/api/v2`

GET`/api/v2/posts`

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

POST`/api/v2/posts`

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

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

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

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

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

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

GET`/api/v2/communities`

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

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

GET`/api/v2/tags`

GET`/api/v2/search`

GET`/api/v2/emojis`

GET`/api/v2/me`

GET`/api/v2/feed`

GET`/api/v2/notifications`

POST`/api/v2/notifications/read`

GET`/api/v2/conversations`

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

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

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

POST`/api/v2/relations`

`Service`

`RateLimit`

`Post`

`Reply`

`Counts`

`Media`

`Poll`

`PollOption`

`ProfileBrief`

`Profile`

`CommunityBrief`

`Community`

`Tag`

`SearchResult`

`Emoji`

`Notification`

`Actor`

`Conversation`

`Message`

`Created`

`Ok`