Publicações

Um post é a legenda, as imagens e uma ou mais contas de destino. Cada conta é um destino (platforms[]) com estado próprio; o status do post é derivado dos destinos.

Criar

curl -X POST https://api.uat.postmatic.dev/v1/posts \
  -H "x-access-key: pm_live_…" \
  -H "content-type: application/json" \
  -d '{
    "content": "Novidade no ar.",
    "platforms": [{ "platform": "instagram", "accountId": "int_…" }],
    "mediaItems": [{ "type": "image", "url": "https://cdn.exemplo.com/foto.jpg" }],
    "scheduledFor": "2026-09-15T13:00:00-03:00",
    "idempotencyKey": "lancamento-2026-09-15"
  }'

Um dos dois, publishNow: true ou scheduledFor, é obrigatório. publishNow: false sem scheduledFor é rejeitado.

Resposta

A API responde 202 e devolve o post no estado inicial. A publicação acontece em segundo plano, mesmo com publishNow.

{
  "success": true,
  "postId": "post_…",
  "status": "scheduled",
  "idempotencyKey": "lancamento-2026-09-15",
  "content": "Novidade no ar.",
  "scheduledFor": "2026-09-15T16:00:00.000Z",
  "timezone": null,
  "profileId": null,
  "platforms": [
    {
      "platform": "instagram",
      "accountId": "int_…",
      "targetId": "tgt_…",
      "status": "pending",
      "platformPostId": null,
      "platformPostUrl": null,
      "errorCode": null,
      "errorMessage": null,
      "attemptCount": 0
    }
  ],
  "mediaUrls": ["https://…/media/…jpg"],
  "createdAt": "2026-09-08T14:00:00.000Z",
  "updatedAt": "2026-09-08T14:00:00.000Z"
}

Antes de aceitar, a Postmatic valida as contas (existem, estão connected, token vivo), baixa e valida as imagens por URL, e consulta a cota de publicação de cada conta na Meta. Qualquer problema vem como erro síncrono: 404 NOT_FOUND, 409 TOKEN_INVALID, 400 MEDIA_INVALID, 409 RATE_LIMIT_ACCOUNT.

Opções do Instagram

Vão em platformSpecificData, dentro de cada entrada de platforms[].

{
  "content": "Bastidores da coleção nova.",
  "platforms": [{
    "platform": "instagram",
    "accountId": "int_…",
    "platformSpecificData": { "shareToFeed": true, "thumbOffset": 1500 }
  }],
  "mediaItems": [{ "type": "video", "url": "https://cdn.exemplo.com/reel.mp4" }],
  "publishNow": true
}

Story

{
  "content": "",
  "platforms": [{ "platform": "instagram", "accountId": "int_…", "platformSpecificData": { "contentType": "story" } }],
  "mediaItems": [{ "type": "image", "url": "https://cdn.exemplo.com/story.jpg" }],
  "publishNow": true
}

Story some do perfil em 24 horas e não aparece na grade. A resposta e o acompanhamento são os mesmos de um post normal; platformPostUrl volta preenchido enquanto a Story está no ar. Conta Creator responde 403 PLATFORM_NOT_AVAILABLE.

Carrossel misto

Imagens e vídeos podem ir juntos em mediaItems. O vídeo de carrossel tem limite de 60 segundos e 100 MB (diferente do Reel), e todos os itens precisam ter a mesma proporção — o Instagram recorta todos para a proporção do primeiro, então a API recusa a diferença acima de 1 % com MEDIA_INVALID, reason: aspect e details.position apontando o item.

Idempotência

Mande um idempotencyKey único por publicação (o id do seu registro, por exemplo). Se a requisição for repetida com a mesma chave, a API devolve 200 com o post original e não cria outro; o corpo da repetição é ignorado. A chave não expira. Sem idempotencyKey, a Postmatic gera um e o devolve na resposta.

Status

Cada destino em platforms[] tem um estado mais fino:

Acompanhar

curl https://api.uat.postmatic.dev/v1/posts/post_… \
  -H "x-access-key: pm_live_…"

Consulte a cada 15 a 30 segundos até o status ser terminal (published, partial ou failed). Uma publicação imediata costuma levar de 30 segundos a 2 minutos; a Meta processa a imagem antes de publicar. Para não ficar em laço, cadastre um webhook e receba o evento final.

Novas tentativas automáticas

Falhas temporárias da Meta (instabilidade, limite do app) recebem novas tentativas sozinhas, com intervalos de 1, 5, 15 e 60 minutos, até 5 tentativas. attemptCount mostra em qual está. Erros definitivos (conta revogada, mídia recusada, conteúdo bloqueado) não são repetidos e o destino vai direto para failed.

Listar

curl "https://api.uat.postmatic.dev/v1/posts?status=scheduled&limit=50" \
  -H "x-access-key: pm_live_…"

A resposta é { success, total, posts[] }, cada post no mesmo formato da criação.

Reagendar

curl -X PATCH https://api.uat.postmatic.dev/v1/posts/post_… \
  -H "x-access-key: pm_live_…" \
  -H "content-type: application/json" \
  -d '{ "scheduledFor": "2026-09-16T13:00:00-03:00", "timezone": "America/Sao_Paulo" }'

Só para posts scheduled. Mesmas regras de janela da criação. Se algum destino já começou, a resposta é 409 POST_NOT_CANCELLABLE.

Cancelar

curl -X DELETE https://api.uat.postmatic.dev/v1/posts/post_… \
  -H "x-access-key: pm_live_…"

Cancela os destinos ainda pendentes. O post não é apagado: fica no histórico com status failed e errorCode: CANCELLED em cada destino. Um post que já entrou em publicação, ou cujo horário já passou, responde 409 POST_NOT_CANCELLABLE. Nada é removido do Instagram.

Repetir destinos que falharam

curl -X POST https://api.uat.postmatic.dev/v1/posts/post_…/retry -H "x-access-key: pm_live_…"

Reabre os destinos em failed, missed ou cancelled com a legenda e a mídia originais; os já published não são tocados. Sem corpo, publica agora; com { "scheduledFor": "…", "timezone": "…" }, agenda de novo. Responde 202 com o post. 400 quando não há nada a repetir; 409 POST_NOT_CANCELLABLE se algum destino ainda está em publicação.

Limites

• Até 10 imagens por post (2 a 10 viram carrossel) e 5 contas por requisição.
• Legenda de até 2.200 caracteres.
• 100 publicações por conta a cada 24 horas, cota da Meta. A Postmatic recusa com RATE_LIMIT_ACCOUNT quando a cota está esgotada.
• Um vídeo por post, publicado como Reel. Stories e carrossel com vídeo ainda não são aceitos; veja o Roadmap.