Agendar Post no Mastodon: Como Definir Horário Futuro pela API

O Mastodon não possui um agendador de posts integrado na interface web ou nos aplicativos oficiais. Para publicar um post em um horário futuro, é necessário usar a API REST do Mastodon diretamente ou por meio de um cliente de terceiros. A API inclui um parâmetro scheduled_at que aceita um timestamp no formato ISO 8601. Este artigo explica como construir a requisição, autenticar e definir um horário futuro de publicação usando uma chamada HTTP simples. Você aprenderá o endpoint exato, os cabeçalhos necessários e as armadilhas comuns ao agendar um post.

Como Funciona a API de Agendamento do Mastodon

A API do Mastodon trata posts agendados como um tipo de recurso separado. Quando você inclui um valor scheduled_at na chamada de criação de status, o servidor não publica o status imediatamente. Em vez disso, ele cria um objeto ScheduledStatus que o servidor processa no horário definido. O servidor armazena o conteúdo do post, anexos de mídia e configurações de visibilidade no objeto agendado. A API retorna um ID de ScheduledStatus que você pode usar para modificar ou cancelar o post antes de ele ser publicado.

Para agendar um post, você precisa de uma conta no Mastodon em qualquer instância e um token de acesso OAuth com o escopo write:statuses. Você pode gerar esse token pela interface web do Mastodon em Preferências > Desenvolvimento > Nova Aplicação. O token deve ter pelo menos o escopo write:statuses. Sem o escopo correto, a API retorna um erro 403 Forbidden. O recurso de agendamento funciona a partir da versão 3.0.0 do Mastodon. Instâncias com versões anteriores ignoram o parâmetro scheduled_at e publicam o post imediatamente.

Requisitos do Timestamp ISO 8601

O valor de scheduled_at deve ser uma string no formato ISO 8601. O Mastodon aceita timestamps com offsets de fuso horário, mas o servidor os converte para UTC para armazenamento. A abordagem mais segura é enviar o timestamp em UTC com o sufixo Z. Por exemplo, 2025-04-15T14:30:00Z representa 14:30 UTC em 15 de abril de 2025. Se você enviar um timestamp com offset de fuso horário como +02:00, o servidor subtrai o offset e armazena o equivalente em UTC. O servidor rejeita timestamps no passado. Se você enviar um horário anterior ao horário atual do servidor, a API retorna um erro 422 Unprocessable Entity.

Passos para Agendar um Post no Mastodon Usando a API

Os passos a seguir assumem que você tem uma conta no Mastodon e um token de acesso com o escopo write:statuses. Você pode usar qualquer cliente HTTP como cURL, Postman ou uma linguagem de programação como Python. Os exemplos usam cURL para clareza.

1. Gere um token de acesso OAuth com escopo write:statuses
   Faça login na sua instância do Mastodon. Vá em Preferências > Desenvolvimento > Nova Aplicação. Digite um nome para a aplicação, como “Agendador”. Em Escopos, selecione write:statuses. Clique em Enviar. Copie o token de acesso exibido na próxima página. Armazene este token com segurança.
2. Construa a requisição POST para /api/v1/statuses
   Defina o método HTTP como POST. Use a URL https://sua-instancia.exemplo/api/v1/statuses. Substitua sua-instancia.exemplo pelo domínio real da sua instância do Mastodon. Defina o cabeçalho Authorization como Bearer SEU_TOKEN_DE_ACESSO. Substitua SEU_TOKEN_DE_ACESSO pelo token do passo 1.
3. Adicione o parâmetro status com o conteúdo do post
   No corpo da requisição, inclua o parâmetro status. Este parâmetro contém o texto do seu post. O comprimento máximo depende da configuração da sua instância. Por exemplo: "status": "Este post foi agendado via API do Mastodon."
4. Adicione o parâmetro scheduled_at com o timestamp futuro
   Inclua o parâmetro scheduled_at no corpo da requisição. O valor deve ser uma string ISO 8601. Por exemplo: "scheduled_at": "2025-04-15T14:30:00Z". Certifique-se de que o timestamp esteja pelo menos um minuto no futuro. O servidor rejeita timestamps com menos de 60 segundos de antecedência.
5. Envie a requisição e verifique a resposta
   Envie a requisição POST. Uma resposta bem-sucedida retorna HTTP 200 com um objeto JSON. O objeto contém um campo id que é o ID do ScheduledStatus. Se você receber um erro 422, verifique o formato do timestamp e certifique-se de que está no futuro. Se receber um erro 403, verifique se seu token inclui o escopo write:statuses.

Erros Comuns na API de Agendamento e Como Evitá-los

API Retorna Erro 422 Unprocessable Entity

Esse erro ocorre com mais frequência porque o timestamp scheduled_at está no passado ou com menos de 60 segundos no futuro. O servidor também rejeita timestamps com mais de 365 dias no futuro. Verifique se o timestamp está no formato ISO 8601 com o sufixo Z. Use uma ferramenta como Epoch Converter para confirmar o horário UTC. Se você estiver gerando o timestamp programaticamente, certifique-se de que o relógio do sistema esteja preciso e configurado para UTC.

Post Publicado Imediatamente em Vez do Horário Agendado

A causa mais comum é a ausência ou erro de digitação no parâmetro scheduled_at. A API ignora parâmetros desconhecidos. Se o nome do parâmetro não for exatamente scheduled_at, o servidor trata a requisição como um post imediato normal. Verifique se há erros de digitação no corpo da requisição. Outra causa é usar uma instância que executa uma versão do Mastodon anterior à 3.0.0. Versões antigas não reconhecem o parâmetro. Você pode verificar a versão da instância acessando https://sua-instancia.exemplo/api/v1/instance e observando o campo version.

Não é Possível Cancelar ou Modificar um Post Agendado

Para cancelar um post agendado, envie uma requisição DELETE para /api/v1/scheduled_statuses/{id} onde {id} é o ID do ScheduledStatus da resposta de criação. Para modificar o conteúdo ou o horário, você deve excluir o status agendado e criar um novo. A API não suporta a atualização de um status agendado existente. Você pode listar todos os posts agendados enviando uma requisição GET para /api/v1/scheduled_statuses. A resposta inclui um array de objetos de status agendados com seus IDs e horários agendados.

Post Agendado vs Post Imediato: Principais Diferenças

Item	Post Agendado	Post Imediato
Endpoint da API	POST /api/v1/statuses com scheduled_at	POST /api/v1/statuses sem scheduled_at
Tipo de resposta	Objeto ScheduledStatus com id	Objeto Status com id
Restrição de tempo	Deve estar entre 60 segundos e 365 dias no futuro	Sem restrição de tempo
Modificação	Excluir e recriar; não há endpoint de atualização	Pode ser editado via PUT /api/v1/statuses/{id}
Suporte a visibilidade	Público, não listado, privado, direto	Público, não listado, privado, direto

A API de agendamento suporta todos os níveis de visibilidade, incluindo mensagens diretas. Anexos de mídia podem ser incluídos enviando-os primeiro via POST /api/v1/media e depois referenciando os IDs de mídia na chamada de criação de status. O parâmetro scheduled_at funciona com o parâmetro media_ids. O servidor valida os anexos de mídia antes de agendar. Se um anexo de mídia falhar no processamento, o post agendado ainda é criado, mas pode ficar sem a mídia quando publicado. Sempre verifique o status de processamento da mídia antes de agendar.

Agora você pode agendar posts no Mastodon a partir de qualquer ferramenta compatível com a API usando o parâmetro scheduled_at no endpoint /api/v1/statuses. Comece gerando um token OAuth com o escopo write:statuses. Teste com um post não sensível com pelo menos 2 minutos de antecedência. Para automação avançada, combine o endpoint de agendamento com um cron job ou uma função serverless que chame a API em intervalos regulares. Lembre-se de tratar o erro 422 validando o timestamp em relação ao relógio do servidor usando o endpoint /api/v1/instance para obter o horário do servidor.