Como migrar listas do Mastodon usando a API

Mover uma conta do Mastodon entre instâncias geralmente preserva seguidores, mas deixa suas listas organizadas para trás. As listas do Mastodon permitem agrupar contas por tópico ou fluxo de trabalho, e recriá-las manualmente pode levar horas. Este artigo explica como exportar os dados das listas da sua conta antiga e importá-los para uma nova usando a API REST do Mastodon. Você aprenderá os endpoints exatos da API, as etapas de autenticação e a formatação de dados necessária para concluir a migração.

Por que as listas do Mastodon não são transferidas durante a migração de conta

O recurso de migração de conta integrado do Mastodon lida com seguidores, solicitações de seguimento, contas silenciadas e contas bloqueadas. As listas não são incluídas nessa transferência porque as listas são locais para cada instância e referenciam IDs de conta que mudam quando você se move para um novo servidor. Cada instância do Mastodon atribui um ID numérico único a cada conta. Após a migração, sua nova conta na instância de destino tem um ID diferente. Os dados da lista antiga contêm os IDs antigos, que não têm significado na nova instância.

Para migrar listas, você deve extrair a estrutura da lista e os IDs das contas membros da instância de origem, recriar cada lista na instância de destino e mapear os IDs antigos para seus equivalentes novos. A API do Mastodon fornece endpoints para todas essas operações. Você pode executar essas etapas manualmente usando uma ferramenta como cURL ou automatizar o processo com um script.

Pré-requisitos para migração de listas baseada em API

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

• Acesso à instância antiga do Mastodon onde suas listas estão atualmente
• Uma conta ativa do Mastodon na instância de destino
• Tokens de acesso à API para ambas as contas (origem e destino)
• Uma ferramenta para fazer requisições HTTP, como cURL, Postman ou um script personalizado em Python ou JavaScript
• Conhecimento dos IDs de conta de cada membro que você deseja adicionar às novas listas

Etapas para exportar listas da instância de origem

A primeira fase envolve coletar todos os metadados das listas e os IDs das contas membros da sua conta antiga do Mastodon. Você precisa de um token de acesso válido para a conta de origem com o escopo read:lists.

1. Gerar um token de acesso na instância de origem
   Vá em Preferências > Desenvolvimento > Nova aplicação. Dê um nome à aplicação, como “Ferramenta de migração de listas”. Ative os escopos read:lists e read:accounts. Salve a aplicação e copie a string do token de acesso.
2. Recuperar todas as listas da conta de origem
   Envie uma requisição GET para https://instancia-origem.exemplo/api/v1/lists com o cabeçalho Authorization: Bearer SEU_TOKEN. A resposta é um array JSON. Cada objeto contém os campos id e title. Registre os IDs e títulos das listas.
3. Buscar IDs de contas membros de cada lista
   Para cada ID de lista da etapa 2, envie uma requisição GET para https://instancia-origem.exemplo/api/v1/lists/ID_DA_LISTA/accounts. A resposta contém um array de objetos de conta. Registre o campo id de cada conta. Salve esses dados em um formato estruturado, como JSON. Exemplo de saída: {"list_title": "Colegas de trabalho", "member_ids": [12345, 67890, 11121]}.

Etapas para importar listas na instância de destino

Após exportar os dados das listas, mude para a instância de destino. Você precisa de um novo token de acesso com os escopos write:lists e write:accounts. Além disso, você deve resolver os IDs de conta antigos para os novos IDs de conta na instância de destino. O método mais simples é pesquisar cada conta pelo nome de usuário e domínio usando o endpoint de pesquisa da API do Mastodon.

1. Gerar um token de acesso na instância de destino
   Navegue até Preferências > Desenvolvimento > Nova aplicação na instância de destino. Nomeie a aplicação e ative os escopos write:lists, write:accounts e read:accounts. Copie o token de acesso.
2. Resolver IDs de conta antigos para novos IDs de conta
   Para cada ID de membro dos seus dados exportados, envie uma requisição GET para https://instancia-destino.exemplo/api/v2/search?q=@usuario@instancia-origem.exemplo&type=accounts&limit=1. O parâmetro q deve conter o handle completo da conta, incluindo o domínio da instância de origem. A resposta inclui um array accounts. Use o campo id do objeto de conta retornado. Armazene esse mapeamento para uso posterior.
3. Criar cada lista na instância de destino
   Para cada título de lista dos seus dados exportados, envie uma requisição POST para https://instancia-destino.exemplo/api/v1/lists com um corpo JSON: {"title": "Colegas de trabalho"}. O cabeçalho deve incluir Content-Type: application/json e Authorization: Bearer SEU_TOKEN. A resposta contém o objeto da nova lista, incluindo seu id.
4. Adicionar contas a cada nova lista
   Para cada nova lista criada na etapa 3, envie uma requisição POST para https://instancia-destino.exemplo/api/v1/lists/ID_DA_LISTA/accounts com um corpo JSON: {"account_ids": ["NOVO_ID_1", "NOVO_ID_2"]}. O array account_ids deve conter os IDs de conta resolvidos na etapa 2. Repita para cada lista.

Problemas comuns e limitações da API

Pesquisa de conta não retorna resultados

O endpoint de pesquisa do Mastodon pode não retornar contas que não estão federadas com a instância de destino. Certifique-se de que a conta que você está pesquisando tenha pelo menos um seguidor ou post que tenha alcançado a instância de destino. Alternativamente, use a interface web da instância de destino para localizar manualmente a conta e copiar seu ID numérico da URL.

Criação de lista falha com erro 422

Isso geralmente significa que o título da lista é muito longo ou contém caracteres inválidos. Os títulos das listas do Mastodon têm um comprimento máximo de 100 caracteres. Remova caracteres especiais ou trunque o título.

Limitação de taxa causando falhas nas requisições

As instâncias do Mastodon impõem limites de taxa nos endpoints da API. Se você tiver um grande número de listas e membros, pode atingir o limite de taxa. Pause entre as requisições ou use backoff exponencial. Verifique o cabeçalho X-RateLimit-Remaining na resposta para monitorar suas requisições restantes.

Endpoints da API do Mastodon para migração de listas

Operação	Método HTTP	Endpoint
Listar todas as listas	GET	/api/v1/lists
Obter membros da lista	GET	/api/v1/lists/:id/accounts
Pesquisar uma conta	GET	/api/v2/search
Criar uma nova lista	POST	/api/v1/lists
Adicionar contas a uma lista	POST	/api/v1/lists/:id/accounts

Agora você tem um método completo para migrar listas do Mastodon entre instâncias usando a API. O processo requer dois tokens de acesso, uma etapa de pesquisa para resolver IDs de conta e a criação sequencial de listas e membros. Para listas grandes com centenas de membros, considere escrever um script em Python ou JavaScript que percorra os dados exportados e lide com a limitação de taxa automaticamente. Após a migração, verifique suas listas abrindo a seção Listas na instância de destino e confirmando que cada lista contém as contas esperadas.