API

Questa è una traduzione. Fa fede la versione tedesca: dove questo testo se ne discosta, vale il tedesco. Puoi cambiare lingua in fondo alla pagina.

Indice

Panoramica

v2 è l’API di tellmelo per i programmi tuoi. Ogni richiesta porta una chiave, ogni risposta è JSON e ogni elenco si sfoglia allo stesso modo. Ciò che accade dietro una chiave passa per le stesse regole di un clic nell’applicazione: limiti di ritmo, sospensioni, diritti ritirati e le impostazioni di questa istanza valgono qui allo stesso modo.

Ogni percorso inizia con /api/v2 all’indirizzo di questa istanza, quello usato negli esempi di questa pagina.
Richieste e risposte sono JSON in UTF-8. Nomi dei campi, codici e valori sono in inglese e restano in inglese.
Una chiave agisce come il tuo account e mai oltre: ciò che non puoi vedere nell’applicazione, nessuna chiave può leggerlo.

https://tellmelo.com/api/v2

Avvio rapido

Crea una chiave in «Impostazioni → App e dati → API» e copiala. Viene mostrata una sola volta.
Interroga con essa la radice. La risposta dice quale versione è in funzione, che cosa può fare la chiave e quante richieste le restano in questo minuto.
Da lì in poi ogni percorso funziona allo stesso modo: la chiave nell’intestazione, JSON in risposta e, per le liste, items e 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"
}

Come proseguire: /me per il tuo profilo, /posts per ciò che è pubblico, /feed per ciò che l’applicazione ti mostra.

La tua chiave

C’è esattamente una chiave per account, legata al tuo identificativo utente. Comincia con tm_key_, così uno scanner la riconosce dove non dovrebbe stare. Viene mostrata una volta sola, nel momento in cui nasce; dopo resta qui solo la sua impronta, e nessuno te la può rileggere, né noi né tu. Chi la smarrisce ne crea una nuova; la vecchia da quel momento non vale più.

La crei in «Impostazioni → App e dati → API». Viaggia nell’intestazione della richiesta, come Authorization: Bearer tm_key_… oppure come X-Tellmelo-Key. Non nella barra degli indirizzi, perché ciò che sta lì finisce nei registri di accesso, nella cronologia del browser e nel referer di ogni link.

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

Oppure, se è più comodo, in un’intestazione propria:

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

Non nella barra degli indirizzi. Ciò che sta lì finisce nel registro di ogni server intermedio, nella cronologia del browser e nel referer di ogni link. Una chiave lì non ci sta.

La stessa chiave carica anche le immagini. Ogni url in una risposta punta a /api/media di questa istanza; manda anche lì la chiave nell’intestazione e l’immagine torna, per quanto il tuo account possa vederla.

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

Che cosa può una chiave

Una chiave porta due diritti, e ogni percorso nelle tabelle qui sotto dice quale dei due gli serve. Due e non cinque: un diritto che non sai spiegarti in una frase è un diritto che spunti senza leggere. E la linea onesta passa fra guardare e cambiare.

read: guardare. I post pubblici, i profili, le community e i tag, e il tuo account così come lo vedi: feed, notifiche, conversazioni, messaggi.
write: cambiare. Tutto ciò che accade a tuo nome: pubblicare, rispondere, votare, inviare messaggi, seguire, entrare, bloccare, segnare le notifiche come lette.

Che cosa nessuna chiave può

Nessuna chiave arriva ai dati del tuo account: né password, né indirizzo e-mail, né tipo di account, né luogo, né ruolo, né eliminazione. Nemmeno gli accessi, né i dispositivi di notifica, né le chiavi stesse: una che potesse emettere chiavi non si potrebbe più spegnere. Nemmeno l’amministrazione, né la guida di una community, perché sciogliere una community o consegnarla è una decisione sui post altrui. Ciò che custodisce la password, nessuna chiave lo può: un segreto che sta in uno script sulla macchina di un altro non deve poter fare ciò che può l’accesso. Prendersi un account costa ancora l’accesso.

Richieste e risposte

JSON ovunque. Ogni risposta è application/json in UTF-8, errori compresi. Solo le immagini arrivano come immagini.
Ciò che invii. Un POST porta i suoi campi come oggetto JSON nel corpo. I parametri dell’indirizzo completano ciò che il corpo non nomina; se entrambi nominano lo stesso campo, vale il corpo.
Gli orari sono numeri interi di millisecondi dal 1° gennaio 1970, UTC, come li conserva la base di dati. Nessun fuso orario da leggere male.
Gli identificativi sono stringhe. Non smontarli e non contare sulla loro forma; confrontali solo per intero.
Ogni campo c’è sempre. Ciò che non esiste è null, mai assente; un conteggio è sempre un numero, una lista sempre una lista, vuota se serve.
I testi sono testo semplice, così come sono stati scritti. #tag, @nomi e link restano come sono, e così gli emoji propri dell’istanza, come :name:; le loro immagini sono elencate in /emojis.
Le immagini sono indirizzi relativi a questa istanza, /api/media?id=…. Caricale con la stessa chiave nell’intestazione; senza, la risposta è 401.

Pagine

Ogni elenco prende limit e cursor e risponde con items e next. Si va avanti rimandando il next dell’ultima risposta come cursor; quando next è vuoto, si è arrivati alla fine. Una pagina piena può comunque essere l’ultima, e chi si ferma solo davanti a una pagina vuota chiede una volta di troppo. Il cursore è opaco: un posto in un elenco, non un istante. Non smontarlo e non costruirtene uno; ciò che contiene può cambiare senza che cambi alcun percorso.

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

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

Una pagina contiene 20 voci senza limit, al massimo 50. Alcune liste non si sfogliano affatto: lo dice il loro percorso, e il loro next è sempre null.

Solo ciò che è nuovo

Ogni risposta porta un ETag. Un programma che chiede di continuo dovrebbe rimandare l’ultimo come If-None-Match: se da allora non è cambiato nulla, la risposta è 304 e non porta corpo. È la differenza fra un elenco che attraversa la linea ogni minuto e uno che la attraversa quando c’è qualcosa dentro, per la tua macchina come per questa.

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

Due eccezioni, entrambe volute: /feed non porta ETag, perché il suo ordine si muove con il tempo e ogni risposta è diversa; e una scrittura non risponde mai 304. Due post uguali sono due post.

Limiti

Una chiave può fare 120 richieste al minuto, 600 con l’abbonamento «Organizzazione», a meno che l’amministrazione non le abbia fissato un altro numero. Il limite vale per chiave, non per account e non per indirizzo. Oltre, la risposta è 429 e non è successo nulla: la richiesta è stata rifiutata, non eseguita. Aspetta un minuto e rimandala; un programma che ci sbatte spesso dovrebbe rallentare invece di richiedere subito.

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

Oltre al limite della chiave, le scritture contano negli stessi limiti dell’applicazione: quanti post, risposte o relazioni in pochi minuti. Anche questi rispondono 429 con il codice rate_limited.

Intestazioni

I nomi sono quelli che ogni libreria client conosce già. Nessuna è obbligatoria, tranne la chiave.

Ciò che invii

Intestazione	Significato
`Authorization`	Porta la chiave: `Bearer tm_key_…`. La via consueta.
`X-Tellmelo-Key`	La chiave, in alternativa ad `Authorization`, per gli strumenti che usano quell’intestazione per altro.
`Content-Type`	`application/json`, per una richiesta con corpo.
`If-None-Match`	L’`ETag` dell’ultima risposta. Se da allora non è cambiato nulla, la risposta è `304` senza corpo.

Ciò che torna

Intestazione	Significato
`ETag`	L’impronta di questa risposta, marcata come debole (`W/`). Rimandala come `If-None-Match`.
`X-RateLimit-Limit`	Quante richieste può fare questa chiave al minuto.
`X-RateLimit-Remaining`	Quante ne restano nel minuto in corso.
`X-RateLimit-Reset`	Quando comincia il minuto successivo, in secondi dal 1970, UTC.
`X-Tellmelo-Scope`	Che cosa può fare questa chiave: `read` o `read write`.
`Retry-After`	Con un `429`: quanti secondi aspettare prima di chiedere di nuovo.
`WWW-Authenticate`	Con un `401` per chiave mancante: `Bearer`, il modo in cui è attesa una chiave.
`Cache-Control`	`no-store`: nessun proxy intermedio può conservare una risposta, perché dipende dalla chiave che chiede. Il tuo programma può comunque verificarla con l’`ETag`.

Quando qualcosa non va

Gli errori arrivano in JSON con due campi: un codice inglese fisso in error, che il tuo programma può confrontare, e una frase in message per la persona davanti, con il codice di stato che le corrisponde. Il codice resta; la frase può cambiare, e può cambiare in ogni lingua: un programma che confronta la frase si rompe in un giorno che nessuno ha annunciato.

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

Alcuni errori portano un campo in più: docs con un 401 per chiave mancante, limit con un 429.

Stato	Codice	Significato
`400`	`bad_request`	La richiesta non si legge, manca un campo obbligatorio o un valore non è tra quelli ammessi. Il `message` dice quale.
`401`	`key_missing`	Nessuna chiave nell’intestazione.
`401`	`key_invalid`	La chiave non è valida: copiata male, sostituita da una nuova, oppure il suo account è sospeso. Quale delle tre, di proposito non si dice.
`401`	`unauthorized`	Rifiutato come non connesso, per un motivo diverso dalla chiave. Raro, e un motivo per guardare l’account dietro la chiave.
`403`	`scope_missing`	Alla chiave manca il diritto che serve a questo percorso: di solito `write` su una chiave che può solo leggere.
`403`	`account_data_locked`	Questo riguarda i dati del tuo account, che nessuna chiave raggiunge: password, indirizzo email, eliminazione e simili.
`403`	`forbidden`	Il tuo account non può farlo: lo stesso rifiuto dell’applicazione, per esempio un diritto revocato o un blocco.
`404`	`unknown_path`	Questo percorso non esiste, o non con questo metodo.
`404`	`not_found`	Il percorso esiste, ma non ciò che nomina, oppure non puoi vederlo. Le due cose non vengono distinte.
`409`	`conflict`	Si scontra con qualcosa che c’è già, per esempio un nome già preso.
`413`	`too_large`	Troppo grande: un testo o una richiesta oltre ciò che questa istanza accetta.
`422`	`unprocessable`	Leggibile, ma non possibile in questa forma.
`429`	`rate_limited`	Troppe richieste. Non è stato fatto nulla; aspetta e inviala di nuovo.
`500`	`internal_error`	Qualcosa è andato storto dalla nostra parte, non dalla tua. È registrato per intero sul server.

Versioni

La versione sta nel percorso. Finché lì c’è scritto v2, questi percorsi e i loro campi restano così; ciò che si aggiunge viene accanto.

Le aggiunte alzano il secondo numero: 2.1 ha portato /emojis e il segnare come letta una conversazione. 2.4 ha tolto il campo contentWarning, perché gli avvisi sui contenuti non esistono più. 2.5 ha tolto il campo alt dalle immagini, perché le descrizioni delle immagini non esistono più. 2.6 aggiunge il tipo di notifica team per il nuovo lavoro del team. Ogni percorso dice da quale versione esiste, e la radice dice quale versione è in funzione.

Percorsi

Tutti i percorsi a colpo d’occhio, poi ciascuno nel dettaglio: che cosa prende, una richiesta d’esempio e che cosa torna.

Percorso	Diritto	A che serve
L’ingresso
GET`/api/v2`	`read`	L’ingresso: quale versione parla questa API e come si chiama questa istanza.
Post
GET`/api/v2/posts`	`read`	I post pubblici, i più recenti per primi.
GET`/api/v2/posts/{id}`	`read`	Un singolo post, tramite il suo `id`.
POST`/api/v2/posts`	`write`	Pubblicare un post.
DELETE`/api/v2/posts/{id}`	`write`	Togliere un tuo post.
Risposte
GET`/api/v2/posts/{id}/replies`	`read`	Le risposte a un post, così come le vedi tu: ciò che ha scritto un account bloccato resta fuori.
POST`/api/v2/posts/{id}/replies`	`write`	Rispondere a un post.
Sondaggi
POST`/api/v2/posts/{id}/vote`	`write`	Partecipare a un sondaggio.
Profili
GET`/api/v2/profiles/{handle}`	`read`	Un profilo, tramite il suo nome breve.
GET`/api/v2/profiles/{handle}/posts`	`read`	I post pubblici di un profilo, i più recenti per primi.
Community
GET`/api/v2/communities`	`read`	Le community aperte di questa istanza.
GET`/api/v2/communities/{id}`	`read`	Una singola community, tramite il suo `id`.
GET`/api/v2/communities/{id}/posts`	`read`	I post pubblici di una community, i più recenti per primi.
Scopri
GET`/api/v2/tags`	`read`	I tag che girano in questo momento.
GET`/api/v2/search`	`read`	Una ricerca su post, nomi, nomi brevi e tag.
GET`/api/v2/emojis`	`read`	Gli emoji propri dell’istanza, con l’indirizzo delle loro immagini.
Il tuo account
GET`/api/v2/me`	`read`	Il tuo profilo, con l’`id` che gli altri percorsi si aspettano.
GET`/api/v2/feed`	`read`	Il tuo feed, come lo compone l’applicazione.
Notifiche
GET`/api/v2/notifications`	`read`	Le tue notifiche, le più recenti per prime, sfogliabili, così un programma recupera ciò che si è perso.
POST`/api/v2/notifications/read`	`write`	Segnare le tue notifiche come lette.
Messaggi
GET`/api/v2/conversations`	`read`	La tua posta: una riga per conversazione, la più recente per prima.
GET`/api/v2/conversations/{with}/messages`	`read`	I messaggi di una conversazione, i più recenti per primi.
POST`/api/v2/conversations/{with}/messages`	`write`	Inviare un messaggio in una conversazione.
POST`/api/v2/conversations/{with}/read`	`write`	Segnare come letti tutti i messaggi di una conversazione.
Relazioni
POST`/api/v2/relations`	`write`	Mettere mi piace, salvare, condividere, seguire, entrare, bloccare, silenziare, a seconda di `kind`.

L’ingresso

La prima richiesta di ogni programma: la chiave funziona, e che cosa può fare?

GET`/api/v2`

L’ingresso: quale versione parla questa API e come si chiama questa istanza.

Diritto read
con ETag
dalla v2.0

Senza barra finale: /api/v2/ reindirizza a /api/v2 con 308, e non tutti i programmi lo seguono.

Richiesta d’esempio

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

Risposta

Risponde con un Service.

Esempio

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

Stati possibili: 200304401429

Post

Leggere i post pubblici, pubblicare i tuoi e toglierli di nuovo.

GET`/api/v2/posts`

I post pubblici, i più recenti per primi.

Diritto read
sfogliabile
con ETag
dalla v2.0

Sui percorsi pubblici le reazioni non si contano: counts.likes e counts.reposts sono 0 e pinned è false (un taglio, non una misura).

I post dentro una community non si raggiungono qui, né nella lista né tramite il loro id. Si leggono in /communities/{id}/posts.

Parametri

Nome	Tipo	Significato
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.
`cursor`nell’indirizzo	`string`facoltativo	Da dove si riprende: il `next` della risposta precedente. Senza, dall’alto.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Post, come `items` e `next`.

Esempio

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

Stati possibili: 200304401429

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

Un singolo post, tramite il suo id.

Diritto read
con ETag
dalla v2.0

Sui percorsi pubblici le reazioni non si contano: counts.likes e counts.reposts sono 0 e pinned è false (un taglio, non una misura).

I post dentro una community non si raggiungono qui, né nella lista né tramite il loro id. Si leggono in /communities/{id}/posts.

Parametri

Nome	Tipo	Significato
`id`nel percorso	`string`obbligatorio	L’`id` di un post.

Richiesta d’esempio

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

Risposta

Risponde con un Post.

Esempio

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

Stati possibili: 200304400401404429

POST`/api/v2/posts`

Pubblicare un post.

Diritto write
dalla v2.0

Un post ha bisogno di testo o di un sondaggio. La lunghezza, il numero di risposte di un sondaggio e quanti post in quanto tempo li stabilisce questa istanza; oltre, la risposta è 400 o 429, con un message che dice quale.

Le immagini non si possono ancora allegare tramite l’API, solo nell’applicazione.

Parametri

Nome	Tipo	Significato
`text`nel corpo	`string`facoltativo	Il testo stesso: del post, della risposta o del messaggio.
`community`nel corpo	`string`facoltativo	L’`id` della community in cui va il post. Senza, fuori da ogni community.
`quotes`nel corpo	`string`facoltativo	L’`id` del post che questo cita.
`poll`nel corpo	`string[]`facoltativo	Le opzioni di risposta di un sondaggio, come elenco di testi. Quante ne sono permesse lo fissa l’istanza.

Richiesta d’esempio

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"

Risposta

Risponde con un Created.

Esempio

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

Stati possibili: 200400401403429

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

Togliere un tuo post.

Diritto write
dalla v2.0

Parametri

Nome	Tipo	Significato
`id`nel percorso	`string`obbligatorio	L’`id` di un post.

Richiesta d’esempio

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

Risposta

Risponde con un Ok.

Esempio

{
  "ok": true
}

Stati possibili: 200400401403404429

Risposte

La conversazione sotto un post: letta come una lista che parentId trasforma in albero, scritta rispondendo al post o a una risposta.

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

Le risposte a un post, così come le vedi tu: ciò che ha scritto un account bloccato resta fuori.

Diritto read
sfogliabile
con ETag
dalla v2.0

La lista è piatta e nell’ordine di scrittura; parentId ne fa un albero. Una pagina contiene fili interi, quindi una risposta non arriva mai senza quella a cui risponde. Ciò che ha scritto un account che hai bloccato, o che ti ha bloccato, resta fuori. Due chiavi possono vedere liste diverse.

Parametri

Nome	Tipo	Significato
`id`nel percorso	`string`obbligatorio	L’`id` di un post.
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.
`cursor`nell’indirizzo	`string`facoltativo	Da dove si riprende: il `next` della risposta precedente. Senza, dall’alto.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Reply, come `items` e `next`.

Esempio

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

Stati possibili: 200304400401404429

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

Rispondere a un post.

Diritto write
dalla v2.0

Sotto un post in modalità lenta ogni persona può rispondere una volta ogni 10 minuti; un’altra risposta riceve 429 con l’attesa nel messaggio. La modalità non vale per l’autore né per gli account che segue.

Parametri

Nome	Tipo	Significato
`id`nel percorso	`string`obbligatorio	L’`id` di un post.
`text`nel corpo	`string`obbligatorio	Il testo stesso: del post, della risposta o del messaggio.
`parentId`nel corpo	`string`facoltativo	L’`id` della risposta a cui questa risponde. Senza, direttamente al post.

Richiesta d’esempio

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"

Risposta

Risponde con un Created.

Esempio

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

Stati possibili: 200400401403404429

Sondaggi

Un sondaggio è un post con poll impostato. Votare ha un percorso tutto suo.

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

Partecipare a un sondaggio.

Diritto write
dalla v2.0

I voti per risposta sono null finché il risultato è trattenuto: prima del tuo voto, mentre il sondaggio è in corso. total c’è sempre.

Parametri

Nome	Tipo	Significato
`id`nel percorso	`string`obbligatorio	L’`id` di un post.
`option`nel corpo	`integer`obbligatorio	Quale risposta, contata da 0. Una per chiamata: un sondaggio con più risposte si vota chiamando più volte.
`retract`nel corpo	`boolean`facoltativo	Se questo voto viene ritirato: `true` lo annulla.

Richiesta d’esempio

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"

Risposta

Risponde con un Ok.

Esempio

{
  "ok": true
}

Stati possibili: 200400401403404429

Profili

Profili pubblici tramite il loro nome breve, e ciò che hanno pubblicato.

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

Un profilo, tramite il suo nome breve.

Diritto read
con ETag
dalla v2.0

Parametri

Nome	Tipo	Significato
`handle`nel percorso	`string`obbligatorio	Il nome breve di un profilo.

Richiesta d’esempio

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

Risposta

Risponde con un Profile.

Esempio

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

Stati possibili: 200304400401404429

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

I post pubblici di un profilo, i più recenti per primi.

Diritto read
sfogliabile
con ETag
dalla v2.0

Sui percorsi pubblici le reazioni non si contano: counts.likes e counts.reposts sono 0 e pinned è false (un taglio, non una misura).

I post dentro una community non si raggiungono qui, né nella lista né tramite il loro id. Si leggono in /communities/{id}/posts.

Parametri

Nome	Tipo	Significato
`handle`nel percorso	`string`obbligatorio	Il nome breve di un profilo.
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.
`cursor`nell’indirizzo	`string`facoltativo	Da dove si riprende: il `next` della risposta precedente. Senza, dall’alto.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Post, come `items` e `next`.

Esempio

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

Stati possibili: 200304400401404429

Community

Le community aperte di questa istanza e i loro post. Quelle interne e quelle nascoste non si raggiungono con una chiave.

GET`/api/v2/communities`

Le community aperte di questa istanza.

Diritto read
con ETag
dalla v2.0

Ordinata per numero di membri, non per data, per questo la lista non si sfoglia, e next è sempre null.

Parametri

Nome	Tipo	Significato
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Community, come `items` e `next`.

Esempio

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

Stati possibili: 200304401429

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

Una singola community, tramite il suo id.

Diritto read
con ETag
dalla v2.0

Parametri

Nome	Tipo	Significato
`id`nel percorso	`string`obbligatorio	L’`id` di una community.

Richiesta d’esempio

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

Risposta

Risponde con un Community.

Esempio

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

Stati possibili: 200304400401404429

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

I post pubblici di una community, i più recenti per primi.

Diritto read
sfogliabile
con ETag
dalla v2.0

Sui percorsi pubblici le reazioni non si contano: counts.likes e counts.reposts sono 0 e pinned è false (un taglio, non una misura).

Parametri

Nome	Tipo	Significato
`id`nel percorso	`string`obbligatorio	L’`id` di una community.
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.
`cursor`nell’indirizzo	`string`facoltativo	Da dove si riprende: il `next` della risposta precedente. Senza, dall’alto.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Post, come `items` e `next`.

Esempio

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

Stati possibili: 200304400401404429

Scopri

Di che cosa si parla, una ricerca tra post, profili e tag, e gli emoji propri dell’istanza.

GET`/api/v2/tags`

I tag che girano in questo momento.

Diritto read
con ETag
dalla v2.0

I tag del momento, quelli con più post per primi. Niente pagine: limit accorcia soltanto la lista.

Parametri

Nome	Tipo	Significato
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Tag, come `items` e `next`.

Esempio

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

Stati possibili: 200304401429

GET`/api/v2/search`

Una ricerca su post, nomi, nomi brevi e tag.

Diritto read
con ETag
dalla v2.0

Cerca solo in ciò che è pubblico: post fuori dalle community, profili e tag. limit conta per tipo: 20 può portare fino a 20 post, 20 profili e 20 tag.

Parametri

Nome	Tipo	Significato
`q`nell’indirizzo	`string`obbligatorio	Le parole cercate.
`type`nell’indirizzo	`string`facoltativo	Che genere di risultato. Senza, ogni genere.`allpostsprofilestags`
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.

Richiesta d’esempio

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

Risposta

Risponde con un SearchResult.

Esempio

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

Stati possibili: 200304400401429

GET`/api/v2/emojis`

Gli emoji propri dell’istanza, con l’indirizzo delle loro immagini.

Diritto read
con ETag
dalla v2.1

Nei testi un emoji di questa istanza compare come :name:. Sostituiscilo con l’immagine di questa lista; un nome che non c’è resta testo: è stato eliminato o non è mai esistito.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Emoji, come `items` e `next`.

Esempio

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

Stati possibili: 200304401429

Il tuo account

Il tuo profilo e il tuo feed, composti come l’applicazione li compone per te.

GET`/api/v2/me`

Il tuo profilo, con l’id che gli altri percorsi si aspettano.

Diritto read
con ETag
dalla v2.0

Richiesta d’esempio

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

Risposta

Risponde con un Profile.

Esempio

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

Stati possibili: 200304401429

GET`/api/v2/feed`

Il tuo feed, come lo compone l’applicazione.

Diritto read
sfogliabile
dalla v2.0

Qui niente ETag: l’ordine si muove con il tempo, quindi ogni risposta è diversa. Una lista iniziata resta comunque la stessa fino alla fine: next porta il momento in cui è cominciata.

Parametri

Nome	Tipo	Significato
`tab`nell’indirizzo	`string`facoltativo	Quale feed: `for-you`, `following`, `latest` o `bookmarks`. `latest` come valore predefinito.`for-youfollowinglatestbookmarks`
`tag`nell’indirizzo	`string`facoltativo	Solo i post con questo tag. Senza, nessun filtro.
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.
`cursor`nell’indirizzo	`string`facoltativo	Da dove si riprende: il `next` della risposta precedente. Senza, dall’alto.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Post, come `items` e `next`.

Esempio

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

Stati possibili: 200400401429

Notifiche

Ciò che è successo intorno al tuo account, leggibile pagina per pagina, perché un programma possa recuperare ciò che ha perso.

GET`/api/v2/notifications`

Le tue notifiche, le più recenti per prime, sfogliabili, così un programma recupera ciò che si è perso.

Diritto read
sfogliabile
con ETag
dalla v2.0

Leggere non segna nulla come letto; lo fa POST /notifications/read. Più eventi dello stesso tipo sullo stesso post vengono raccolti in una riga, e more dice quanti.

Parametri

Nome	Tipo	Significato
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.
`cursor`nell’indirizzo	`string`facoltativo	Da dove si riprende: il `next` della risposta precedente. Senza, dall’alto.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Notification, come `items` e `next`.

Esempio

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

Stati possibili: 200304401429

POST`/api/v2/notifications/read`

Segnare le tue notifiche come lette.

Diritto write
dalla v2.0

Richiesta d’esempio

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

Risposta

Risponde con un Ok.

Esempio

{
  "ok": true
}

Stati possibili: 200401403429

Messaggi

La tua casella e le tue conversazioni. Una conversazione non ha un identificativo proprio; prende il nome dall’altro account.

GET`/api/v2/conversations`

La tua posta: una riga per conversazione, la più recente per prima.

Diritto read
sfogliabile
con ETag
dalla v2.0

Parametri

Nome	Tipo	Significato
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.
`cursor`nell’indirizzo	`string`facoltativo	Da dove si riprende: il `next` della risposta precedente. Senza, dall’alto.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Conversation, come `items` e `next`.

Esempio

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

Stati possibili: 200304401429

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

I messaggi di una conversazione, i più recenti per primi.

Diritto read
sfogliabile
con ETag
dalla v2.0

Leggere non segna nulla come letto: un programma che scarica in background non ha mostrato niente a nessuno. Lo fa POST /conversations/{with}/read.

Parametri

Nome	Tipo	Significato
`with`nel percorso	`string`obbligatorio	L’`id` dell’account con cui parli. Una conversazione non ha un `id` suo: è l’altro account, lo stesso valore che la posta chiama `with`.
`limit`nell’indirizzo	`integer`facoltativo	Quante voci tiene una pagina: 20 come valore predefinito, 50 al massimo.
`cursor`nell’indirizzo	`string`facoltativo	Da dove si riprende: il `next` della risposta precedente. Senza, dall’alto.

Richiesta d’esempio

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

Risposta

Risponde con una pagina di Message, come `items` e `next`.

Esempio

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

Stati possibili: 200304400401404429

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

Inviare un messaggio in una conversazione.

Diritto write
dalla v2.0

Valgono le stesse regole dell’applicazione: a chi ti ha bloccato non si può scrivere, e contano le impostazioni dell’altra persona. La risposta dice allora perché.

Le immagini non si possono ancora allegare tramite l’API, solo nell’applicazione.

Parametri

Nome	Tipo	Significato
`with`nel percorso	`string`obbligatorio	L’`id` dell’account con cui parli. Una conversazione non ha un `id` suo: è l’altro account, lo stesso valore che la posta chiama `with`.
`text`nel corpo	`string`obbligatorio	Il testo stesso: del post, della risposta o del messaggio.
`replyTo`nel corpo	`string`facoltativo	L’`id` di un messaggio precedente di questa conversazione a cui questo risponde. Dalla 2.2.

Richiesta d’esempio

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"

Risposta

Risponde con un Ok.

Esempio

{
  "ok": true
}

Stati possibili: 200400401403404429

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

Segnare come letti tutti i messaggi di una conversazione.

Diritto write
dalla v2.1

Parametri

Nome	Tipo	Significato
`with`nel percorso	`string`obbligatorio	L’`id` dell’account con cui parli. Una conversazione non ha un `id` suo: è l’altro account, lo stesso valore che la posta chiama `with`.

Richiesta d’esempio

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

Risposta

Risponde con un Ok.

Esempio

{
  "ok": true
}

Stati possibili: 200400401403404429

Relazioni

Mi piace, salvare, ricondividere, seguire, unirsi e bloccare: un solo percorso per tutto, impostato e ritirato con active.

POST`/api/v2/relations`

Mettere mi piace, salvare, condividere, seguire, entrare, bloccare, silenziare, a seconda di kind.

Diritto write
dalla v2.0

target è un post per like, save e repost, una community per join, un account per follow, block e mute, sempre tramite il suo id. active: false ritira la relazione. Nessuno può seguire attraverso un blocco, in nessuna direzione. Solo chi silenzia vede il silenziamento.

Parametri

Nome	Tipo	Significato
`kind`nel corpo	`string`obbligatorio	Quale relazione: `like`, `save`, `repost`, `follow`, `join`, `block` o `mute` (dalla 2.2).`likesaverepostfollowjoinblockmute`
`target`nel corpo	`string`obbligatorio	A che cosa punta la relazione, tramite il suo `id`: un post, un profilo o una community, a seconda di `kind`.
`active`nel corpo	`boolean`facoltativo	Se la relazione deve valere: `true` la mette, `false` la toglie.

Richiesta d’esempio

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"

Risposta

Risponde con un Ok.

Esempio

{
  "ok": true
}

Stati possibili: 200400401403429

Oggetti

Tutto ciò che una risposta può contenere, campo per campo. Ogni campo è sempre presente; i tipi sono tipi JSON, e [] significa una lista.

`Service`

La risposta della radice: chi risponde e che cosa può fare questa chiave.

Campo	Tipo	Significato
`name`	`string`	Sempre `tellmelo`.
`version`	`string`	La versione dell’API, per esempio `2.1`.
`scope`	`string`	Che cosa può fare questa chiave: `read` o `read write`.
`rateLimit`	`RateLimit`	La quota di questa chiave.
`docs`	`string`	Dove si trova questa documentazione, come percorso su questa istanza.
`spec`	`string`	Dove si trova la descrizione leggibile dalle macchine.

Esempio

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

`RateLimit`

La quota di questa chiave nel minuto in corso.

Campo	Tipo	Significato
`limit`	`integer`	Richieste al minuto.
`remaining`	`integer`	Quante ne restano in questo minuto.

Esempio

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

`Post`

Un post: la stessa forma ovunque, che sia pubblico, dal tuo feed o da una ricerca.

Campo	Tipo	Significato
`id`	`string`	L’identificativo del post.
`text`	`string`o null	Il testo come è stato scritto (`null` per un post che è solo un sondaggio o solo immagini).
`kind`	`string`	Che cosa è il post. `post` — Un post con testo, immagini o una citazione. `poll` — Un post con un sondaggio.
`author`	`ProfileBrief`	Chi l’ha scritto.
`community`	`CommunityBrief`o null	La community in cui è stato scritto (`null` fuori da ogni community).
`media`	`Media[]`	Le sue immagini, in ordine; vuota se non ce ne sono.
`poll`	`Poll`o null	Il sondaggio (`null` se non c’è).
`quotes`	`string`o null	L’identificativo del post che questo cita.
`continues`	`string`o null	L’identificativo del post che questo prosegue, come aggiunta.
`counts`	`Counts`	Risposte, mi piace e ricondivisioni.
`pinned`	`boolean`	Se è fissato in cima al profilo di chi l’ha scritto.
`createdAt`	`integer`	Quando è stato scritto.

Esempio

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

Una risposta sotto un post: un post con due campi in più.

Ogni campo di Post e, in più:

Campo	Tipo	Significato
`postId`	`string`	Il post a cui è appesa tutta la conversazione.
`parentId`	`string`o null	La risposta a cui risponde questa (`null` se risponde direttamente al post).

Esempio

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

Quante risposte, mi piace e ricondivisioni ha un post.

Campo	Tipo	Significato
`replies`	`integer`	Le risposte, tutti i livelli insieme.
`likes`	`integer`	I mi piace.
`reposts`	`integer`	Le ricondivisioni.

Esempio

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

`Media`

Un’immagine di un post o di un messaggio.

Campo	Tipo	Significato
`url`	`string`	L’indirizzo dell’immagine, relativo a questa istanza. Caricala con la chiave nell’intestazione.

Esempio

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

`Poll`

Il sondaggio di un post.

Campo	Tipo	Significato
`options`	`PollOption[]`	Le risposte, in ordine. `option` nel voto conta da 0.
`total`	`integer`	Quanti voti ci sono in totale: sempre, anche mentre la ripartizione è trattenuta.
`multiple`	`boolean`	Se si può scegliere più di una risposta.
`endsAt`	`integer`o null	Quando finisce il sondaggio (`null` se non ha fine).
`running`	`boolean`	Se si può ancora votare.
`resultsVisible`	`boolean`	Se i voti per risposta vengono mostrati (vedi `votes`).
`myVotes`	`integer[]`	Le risposte che hai scelto, contate da 0.

Esempio

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

Una risposta di un sondaggio.

Campo	Tipo	Significato
`text`	`string`	La risposta.
`votes`	`integer`o null	I suoi voti (`null` finché il risultato è trattenuto).

Esempio

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

`ProfileBrief`

Un profilo come compare dentro altri oggetti: come autore, in una ricerca.

Campo	Tipo	Significato
`id`	`string`	L’identificativo dell’account: ciò che si aspettano `/relations` e `/conversations/{with}`.
`handle`	`string`	Il nome breve, senza `@`. Fa parte dell’indirizzo del profilo e non può contenere emoji.
`name`	`string`	Il nome visualizzato. Può contenere emoji, anche `:name:`.
`verified`	`boolean`	Se l’account è verificato.
`accountKind`	`string`	Che tipo di account è. `person` — Una persona. `business` — Un’azienda. `association` — Un’associazione. `automated` — Un account automatico, per esempio un bot.

Esempio

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

`Profile`

Un profilo da solo, con la sua descrizione e i suoi follower.

Ogni campo di ProfileBrief e, in più:

Campo	Tipo	Significato
`about`	`string`o null	La descrizione (`null` se non c’è).
`website`	`string`o null	Il sito web del profilo (`null` se non c’è). Dalla 2.3.
`websiteVerified`	`boolean`	Se il sito rimanda a questo profilo con `rel=me`, controllato nell’ultima settimana. Dalla 2.3.
`followers`	`integer`	Quanti account lo seguono.
`createdAt`	`integer`	Quando è stato creato l’account.

Esempio

{
  "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 community in cui è stato scritto un post.

Campo	Tipo	Significato
`id`	`string`	L’identificativo della community.
`name`	`string`o null	Il suo nome.

Esempio

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

`Community`

Una community di questa istanza.

Campo	Tipo	Significato
`id`	`string`	L’identificativo della community.
`name`	`string`	Il suo nome.
`description`	`string`o null	La descrizione (`null` se non c’è).
`tags`	`string[]`	Gli argomenti di cui si occupa.
`members`	`integer`	Quanti membri ha.
`joinPolicy`	`string`	Come si entra. `open` — Chiunque può unirsi. `application` — Per unirsi serve una candidatura che la community accetta. `invite` — Solo su invito.
`visibility`	`string`	Chi può vederla. Tramite una chiave sempre `open`: le altre non si raggiungono. `open` — Visibile a tutti.

Esempio

{
  "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 e quanti post lo portano.

Campo	Tipo	Significato
`tag`	`string`	Il tag, senza `#`.
`posts`	`integer`	Quanti post recenti lo portano.

Esempio

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

`SearchResult`

Ciò che trova una ricerca: tre liste, ognuna forse vuota, mai assente.

Campo	Tipo	Significato
`posts`	`Post[]`	Post trovati, i più recenti per primi.
`profiles`	`ProfileBrief[]`	Profili trovati, per nome breve.
`tags`	`Tag[]`	Tag trovati, i più usati per primi.

Esempio

{
  "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 emoji di questa istanza.

Campo	Tipo	Significato
`name`	`string`	Il nome, come compare tra i due punti.
`url`	`string`	L’indirizzo dell’immagine, relativo a questa istanza.

Esempio

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

`Notification`

Una notifica. Una riga può raccogliere più eventi dello stesso tipo.

Campo	Tipo	Significato
`id`	`string`	L’identificativo della notifica.
`kind`	`string`	Che cosa è successo. `reply` — Qualcuno ti ha risposto. `like` — A qualcuno piace il tuo post. `repost` — Qualcuno ha ricondiviso il tuo post. `follow` — Qualcuno ti segue. `mention` — Qualcuno ti ha menzionato. `group_mention` — Qualcuno ha menzionato un gruppo che guidi; `text` è il suo nome. `message` — Qualcuno ti ha scritto un messaggio. `scheduled` — Un tuo post programmato è stato pubblicato. `reminder` — È arrivato un promemoria su un post salvato. `report` — Che cosa è successo a una segnalazione che hai inviato. `moderation` — Una decisione sul tuo account: un avvertimento, una limitazione, un ricorso. `team` — Nuovo lavoro per il team, solo per proprietari, admin e moderatori: segnalazioni, ricorsi, link inviati, richieste, richieste di verifica e disdette.
`text`	`string`o null	Solo per segnalazioni e moderazione: il testo che l’accompagna. Altrimenti `null`: la frase di una notifica la costruisce il tuo programma.
`actor`	`Actor`	Chi l’ha fatto.
`postId`	`string`o null	Il post di cui si tratta (`null` se non riguarda alcun post).
`read`	`boolean`	Se è stata segnata come letta.
`more`	`integer`	Per quanti altri eventi vale questa riga, oltre a quello nominato.
`createdAt`	`integer`	Quando è successo la prima volta.
`updatedAt`	`integer`	Quando ha raccolto l’ultimo evento. La lista è ordinata così.

Esempio

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

Chi ha fatto scattare una notifica.

Campo	Tipo	Significato
`handle`	`string`	Il nome breve.
`name`	`string`	Il nome visualizzato.

Esempio

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

`Conversation`

Una riga della tua casella.

Campo	Tipo	Significato
`with`	`string`	L’identificativo dell’altro account: ciò che si aspetta `/conversations/{with}/messages`.
`handle`	`string`	Il suo nome breve.
`name`	`string`	Il suo nome visualizzato.
`excerpt`	`string`o null	L’inizio dell’ultimo messaggio (`null` se non ha testo).
`truncated`	`boolean`	Se l’estratto è stato accorciato.
`fromMe`	`boolean`	Se l’ultimo messaggio è tuo.
`lastMessageId`	`string`	L’identificativo dell’ultimo messaggio.
`unread`	`integer`	Quanti dei suoi messaggi non hai ancora letto.
`updatedAt`	`integer`	Quando è stato scritto l’ultimo messaggio.

Esempio

{
  "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 messaggio in una conversazione.

Campo	Tipo	Significato
`id`	`string`	L’identificativo del messaggio.
`text`	`string`o null	Il testo (`null` per un messaggio fatto solo di immagini).
`from`	`string`	L’identificativo dell’account che l’ha scritto.
`to`	`string`	L’identificativo dell’account a cui è stato scritto.
`read`	`boolean`	Se chi l’ha ricevuto l’ha letto.
`media`	`Media[]`	Le sue immagini; vuota se non ce ne sono.
`replyTo`	`string`o null	L’`id` del messaggio a cui questo risponde (`null` se non risponde a nessuno). Dalla 2.2.
`createdAt`	`integer`	Quando è stato inviato.

Esempio

{
  "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 risposta di una scrittura che ha creato qualcosa.

Campo	Tipo	Significato
`id`	`string`	L’identificativo di ciò che è stato creato.
`scheduledFor`	`integer`o null	Quando compare, se la pubblicazione è stata programmata (altrimenti `null`).
`deleteAt`	`integer`o null	Quando si elimina da solo, se è stato impostato (altrimenti `null`).

Esempio

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

`Ok`

La risposta di una scrittura che non ha niente da restituire.

Campo	Tipo	Significato
`ok`	`boolean`	Sempre `true`.

Esempio

{
  "ok": true
}

La descrizione leggibile da una macchina

La stessa tabella con cui è costruita questa pagina sta sotto /api/v2/openapi.json: percorsi, parametri, diritti e le forme che tornano. Un generatore di client può leggerla, e non può allontanarsi dall’API, perché la pagina, il router e la descrizione vengono da un solo elenco.

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

Che fine ha fatto v1

v1 è stata rimossa. I vecchi percorsi sotto /api/v1/ rispondono 410 e dicono nel corpo dove andare. Nessun reindirizzamento, perché v2 risponde in un’altra forma, e un programma che lo seguisse riceverebbe un 200 che non sa leggere. A quel punto non c’erano ancora account pubblici e quindi nessuno con un programma sopra; toglierla più tardi avrebbe voluto dire non toglierla mai.

Che cosa ci aspettiamo

Gli stessi principi di sempre: niente molestie, niente spam, nessun contenuto altrui senza averne diritto. Un programma non scusa nulla: di ciò che scrive la tua chiave rispondi tu.

API

Panoramica

Avvio rapido

La tua chiave

Che cosa può una chiave

Che cosa nessuna chiave può

Richieste e risposte

Pagine

Solo ciò che è nuovo

Limiti

Intestazioni

Ciò che invii

Ciò che torna

Quando qualcosa non va

Versioni

Percorsi

L’ingresso

GET/api/v2

Richiesta d’esempio

Risposta

Post

GET/api/v2/posts

Parametri

Richiesta d’esempio

Risposta

GET/api/v2/posts/{id}

Parametri

Richiesta d’esempio

Risposta

POST/api/v2/posts

Parametri

Richiesta d’esempio

Risposta

DELETE/api/v2/posts/{id}

Parametri

Richiesta d’esempio

Risposta

Risposte

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

Parametri

Richiesta d’esempio

Risposta

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

Parametri

Richiesta d’esempio

Risposta

Sondaggi

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

Parametri

Richiesta d’esempio

Risposta

Profili

GET/api/v2/profiles/{handle}

Parametri

Richiesta d’esempio

Risposta

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

Parametri

Richiesta d’esempio

Risposta

Community

GET/api/v2/communities

Parametri

Richiesta d’esempio

Risposta

GET/api/v2/communities/{id}

Parametri

Richiesta d’esempio

Risposta

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

Parametri

Richiesta d’esempio

Risposta

Scopri

GET/api/v2/tags

Parametri

Richiesta d’esempio

Risposta

GET/api/v2/search

Parametri

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`