Como Usar a API de Seguir Tags do Mastodon para Automação

Usuários do Mastodon podem seguir hashtags para ver postagens públicas que incluem essas tags em seu feed principal. Esse recurso ajuda a monitorar tópicos sem pesquisar manualmente ou adicionar cada usuário que publica sobre eles. A API de Seguir Tags expõe essa funcionalidade de forma programática, permitindo que scripts de automação sigam ou deixem de seguir tags para uma conta de usuário. Este artigo explica como autenticar na API do Mastodon, localizar o endpoint correto e escrever um script básico para seguir ou deixar de seguir uma hashtag.

O que a API de Seguir Tags Faz e o que Você Precisa Antes de Usá-la

A API de Seguir Tags do Mastodon faz parte da REST API v1. Ela permite gerenciar quais hashtags sua conta segue. Quando você segue uma hashtag, seu feed principal mostra postagens públicas que usam essa tag, desde que venham de contas na sua instância ou sejam impulsionadas por alguém que você segue.

Antes de começar, você precisa do seguinte:

• Uma conta no Mastodon em qualquer instância que suporte acesso à API (a maioria suporta)
• Um aplicativo registrado nessa instância para obter um token de acesso
• O token de acesso com os escopos read e write:follows
• Familiaridade básica com requisições HTTP e uma ferramenta como curl ou uma linguagem de programação como Python

O endpoint da API para seguir uma tag é POST /api/v1/tags/:id/follow, onde :id é o nome da tag codificado na URL (sem o # inicial). Por exemplo, para seguir a tag python, você chama POST /api/v1/tags/python/follow. A resposta retorna um objeto Tag com o atributo following definido como true.

Para deixar de seguir, use POST /api/v1/tags/:id/unfollow e retorna o objeto Tag com following definido como false. Para listar todas as tags que você segue, chame GET /api/v1/followed_tags com suporte a paginação.

Passos para Automatizar o Seguimento e o Deixar de Seguir Tags

Os passos a seguir assumem que você já registrou um aplicativo e obteve um token de acesso. Se ainda não fez isso, consulte a documentação da API do Mastodon para criar um aplicativo e solicitar um token OAuth com os escopos read e write:follows.

1. Identifique o nome da tag
   Decida qual hashtag você quer seguir ou deixar de seguir. Escreva o nome da tag sem o símbolo #. Por exemplo, se a tag é #mastoadmin, use mastoadmin na chamada da API.
2. Construa a URL do endpoint da API
   A URL base da sua instância é algo como https://mastodon.exemplo. Acrescente o caminho do endpoint. Para seguir: https://mastodon.exemplo/api/v1/tags/mastoadmin/follow. Para deixar de seguir: https://mastodon.exemplo/api/v1/tags/mastoadmin/unfollow.
3. Defina o cabeçalho de Autorização
   Toda chamada à API deve incluir o cabeçalho Authorization: Bearer SEU_TOKEN_DE_ACESSO. Substitua SEU_TOKEN_DE_ACESSO pelo token que você obteve do seu aplicativo.
4. Envie a requisição POST
   Use curl ou sua biblioteca HTTP preferida. Para curl, o comando é assim:
   curl -X POST "https://mastodon.exemplo/api/v1/tags/mastoadmin/follow" -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"
   A resposta JSON contém o objeto da tag. Procure pelo campo following. Se for true, a operação foi bem-sucedida.
5. Verifique o resultado
   Para confirmar que a tag agora está sendo seguida, chame GET /api/v1/followed_tags com o mesmo cabeçalho de Autorização. A resposta é um array de objetos de tag. Verifique se sua tag aparece na lista.

Exemplo de Script em Python

O script Python a seguir usa a biblioteca requests para seguir uma tag:

import requests

INSTANCIA = "https://mastodon.exemplo"
TOKEN = "SEU_TOKEN_DE_ACESSO"
TAG = "mastoadmin"

headers = {"Authorization": f"Bearer {TOKEN}"}
url = f"{INSTANCIA}/api/v1/tags/{TAG}/follow"
response = requests.post(url, headers=headers)

if response.status_code == 200:
    dados = response.json()
    print(f"Seguindo tag: {dados['following']}")
else:
    print(f"Erro {response.status_code}: {response.text}")

Substitua os placeholders pela URL da sua instância e token. Execute o script. A saída mostra se a tag agora está sendo seguida.

Deixar de Seguir uma Tag via Script

Para deixar de seguir, altere o endpoint de /follow para /unfollow:

url = f"{INSTANCIA}/api/v1/tags/{TAG}/unfollow"
response = requests.post(url, headers=headers)

O script funciona de forma idêntica. Após executá-lo, o campo following na resposta será false.

Erros Comuns, Limitações e Coisas a Evitar

Usar o Método HTTP Errado

Os endpoints de seguir e deixar de seguir exigem requisições POST. Usar GET retorna um erro 404 ou 405. Sempre verifique o método HTTP antes de enviar a requisição.

Escopos Ausentes ou Incorretos

Se seu token de acesso não tiver o escopo write:follows, a API retorna um erro 403 Forbidden. Ao criar o aplicativo, solicite explicitamente os escopos read e write:follows. Regere o token se necessário.

Codificação do Nome da Tag

Se a tag contiver caracteres especiais, como espaços ou letras não ASCII, você deve codificar o nome da tag na URL. Por exemplo, a tag #machine learning se torna machine%20learning no caminho do endpoint. A maioria das bibliotecas HTTP lida com isso automaticamente se você passar o nome da tag como parâmetro.

Limitação de Taxa

As instâncias do Mastodon impõem limites de taxa nas chamadas à API. Seguir ou deixar de seguir muitas tags em rápida sucessão pode causar bloqueios temporários. Espaçe suas requisições com pelo menos um segundo de intervalo. Verifique o cabeçalho X-RateLimit-Remaining na resposta para monitorar sua cota.

Seguir uma Tag que Não Existe

A API não valida se a tag já foi usada. Você pode seguir uma tag que não tem postagens. Isso não é um erro, mas não adicionará conteúdo ao seu feed até que alguém publique com essa tag.

Métodos da API do Mastodon para Gerenciamento de Tags

Item	Seguir Tag	Deixar de Seguir Tag	Listar Tags Seguidas
Método HTTP	POST	POST	GET
Endpoint	/api/v1/tags/:id/follow	/api/v1/tags/:id/unfollow	/api/v1/followed_tags
Escopo Necessário	write:follows	write:follows	read
Resposta	Objeto Tag com following: true	Objeto Tag com following: false	Array de objetos Tag
Idempotente	Sim (repetir não tem efeito extra)	Sim	Sim

A tabela mostra que tanto seguir quanto deixar de seguir usam POST e exigem o mesmo escopo. O endpoint de listagem usa GET e requer apenas o escopo read. Nenhuma dessas operações é destrutiva além de alterar o estado de seguimento.

Agora você pode escrever scripts de automação para gerenciar assinaturas de hashtag no Mastodon. Comece testando a API com uma única tag usando curl. Depois, expanda seu script para seguir uma lista de tags a partir de um arquivo de configuração. Para cenários avançados, use os parâmetros de paginação max_id e since_id no endpoint followed_tags para processar listas grandes de forma eficiente.