Como agendar posts via API
Como agendar posts em redes sociais programaticamente, com horário exato e fuso horário tratados corretamente.
Por André Lug"Agendar um post" pode significar duas coisas bem diferentes numa API: marcar um post específico para sair num instante exato, ou criar um template que se repete sozinho. O PostGate trata os dois casos com recursos distintos — o campo scheduled_at dentro de POST /api/posts para o primeiro, e o recurso de schedules para o segundo. Confundir os dois é a causa mais comum de gente tentando simular recorrência com um cron chamando o endpoint de post na mão.
Se o que você precisa é só publicar um post agora, veja como postar no Instagram via API primeiro.
Agendamento pontual vs. recorrente
Um agendamento pontual é um post só, que existe desde já no estado scheduled e publica sozinho num horário fixo. Um schedule recorrente não é um post — é um template (corpo, perfis, mídia) que o PostGate materializa em novos posts automaticamente, seguindo uma expressão cron ou uma lista de horários fixos. Use agendamento pontual para "esse conteúdo específico sai terça às 14h". Use um schedule recorrente para "todo dia útil às 9h, o que estiver na fila".
Um post agendado para um horário exato
Passe um scheduled_at em formato ISO 8601 no mesmo envelope usado para publicação imediata. O post fica no estado scheduled até o horário chegar, e pode ser atualizado ou cancelado enquanto ainda não foi publicado.
curl -X POST https://postgate.studio/api/posts \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-terca-14h" \
-d '{
"post": { "body": "Vai ao ar terça às 14h." },
"profiles": ["pro_instagram123"],
"media": ["https://cdn.example.com/launch.jpg"],
"scheduled_at": "2026-09-02T14:00:00-03:00"
}'Criar um schedule recorrente com cron
O template de um schedule usa o mesmo envelope de post, perfis e mídia de sempre — a diferença é a expressão cron e o fuso horário, que definem quando cada novo post vai ser materializado a partir dali.
curl -X POST https://postgate.studio/api/schedules \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Atualização de segunda a sexta",
"kind": "cron",
"expression": "0 9 * * 1-5",
"timezone": "America/Sao_Paulo",
"template": {
"post": { "body": "Bom dia da nossa equipe." },
"profiles": ["pro_linkedin456"],
"media": []
}
}'Usar uma fila de horários em vez de cron
Quando o que você quer é uma fila simples de horários fixos por dia — sem escrever uma expressão cron — use kind: "slots" com uma lista de horários no formato HH:mm, como 09:00, 13:30, 18:00. Depois, um post criado com scheduled_at: "queue" pega o próximo horário disponível dessa fila automaticamente, em vez de você calcular o próximo slot livre no seu próprio código.
Pausar sem perder a configuração
Um PATCH com active: false interrompe a materialização de novos posts sem apagar o schedule — útil para pausar uma campanha temporariamente. Mudar a expressão cron ou o fuso horário reseta o horizonte de materialização, então trate essas duas alterações como uma mudança estrutural, não um ajuste fino.
