Publicação

Este guia acompanha um post do começo ao fim: encontrar o canal, conferir o que a rede dele exige, criar o post e depois agendá-lo, colocá-lo na fila ou publicá-lo na hora. Todos os exemplos rodam em https://post.chatclean.com.br/api com uma chave de API do workspace.

Os exemplos deste guia seguem a API atual do PostClean. Algumas páginas da referência de endpoints ainda descrevem campos de uma versão mais nova do projeto original (por exemplo, social_account_id no nível de cima em Create post). Quando houver diferença, vale o que está neste guia.

Liste as contas sociais

Encontre o canal em que vai publicar e veja os limites dele.

Confira os tipos de conteúdo

Escolha um formato e preencha as configurações que a rede exige.

Crie o post

Um post por canal, ou uma chamada para vários canais.

Agende, coloque na fila ou publique

Num horário definido, na fila do canal ou agora.

1. Liste as contas sociais

List social accounts devolve os canais conectados ao workspace. Os canais são conectados e removidos no app; a API só os lê.

curl https://post.chatclean.com.br/api/social-accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "data": [
    {
      "id": "9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54",
      "platform": "x",
      "display_name": "PostClean",
      "username": "postclean",
      "status": "connected",
      "has_posting_schedule": true,
      "timezone": "America/Sao_Paulo",
      "posting_goal": 5,
      "max_content_length": 280,
      "long_posts": false,
      "verified_badge": null
    }
  ],
  "links": { "...": "..." },
  "meta": { "...": "..." }
}

Os campos que importam para publicar:

Campo	Uso
`id`	O `social_account_id` do post
`platform`	A rede, que define os tipos de conteúdo e as configurações abaixo
`status`	Só contas `connected` publicam. Contas `disconnected` e `token_expired` precisam ser reconectadas no app
`max_content_length`	O limite de texto desta conta. Contas do X com posts longos (`long_posts: true`) têm 25000 em vez de 280
`has_posting_schedule`	Se o canal tem horários de publicação, que a fila precisa
`timezone`	O fuso horário do canal. Os horários da fila e as recorrências seguem esse fuso

2. Confira os tipos de conteúdo

List content types descreve cada rede: seus tipos de conteúdo, limites de texto e de hashtags, as configurações obrigatórias e a mídia que cada formato aceita.

curl https://post.chatclean.com.br/api/content-types \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Leia estes campos antes de montar um post:

Campo	Significado
`default_content_type`	O formato usado quando você omite `content_type`
`content_types[].value`	O valor a enviar em `content_type`, por exemplo `instagram_reel`
`required_meta`	Configurações que precisam estar em `meta` antes de o post poder ser agendado ou publicado
`max_content_length`	O limite de texto da rede. O que vale é o limite da própria conta (`max_content_length` na conta social)
`max_hashtags`	Limite de hashtags: `5` no Instagram, `null` nas demais redes
`content_types[].captionless`	`true` quando o formato não envia texto (Stories do Instagram e do Facebook)
`content_types[].supports_thread_replies`	`true` quando o formato aceita respostas em fio (X, Bluesky e Mastodon), com `max_thread_replies` (24)
`content_types[].requires_media`, `min_media_count`, `max_media_count`	A mídia que o formato exige

Quando você omite content_type, ele é escolhido como no app: no Pinterest, um vídeo vira pinterest_video_pin e várias imagens viram pinterest_carousel; no TikTok, só imagens viram tiktok_photo; as outras redes usam o formato padrão.

Configurações obrigatórias

O post leva as configurações da rede em meta. Um rascunho pode ser salvo sem elas; agendar ou publicar exige que estejam preenchidas:

Rede	Obrigatório em `meta`	Onde conseguir o valor
TikTok	`privacy_level`: `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR` ou `SELF_ONLY`	Get TikTok creator info lista os níveis que a conta permite
Pinterest	`board_id`	List Pinterest boards ou Create Pinterest board
Discord	`channel_id`	List Discord channels
YouTube	Um título: `title`, ou a primeira linha do texto	Até 100 caracteres, sem `<` nem `>`
Google Business	`event` com `title`, `start_date` e `end_date` quando `topic_type` é `EVENT` ou `OFFER`; um `call_to_action` precisa de `url`, a menos que o `action_type` seja `NONE` ou `CALL`	Definido por você

As demais configurações são opcionais: prévias de links, rótulos de conteúdo gerado por IA, privacidade e categoria no YouTube, avisos de conteúdo no Mastodon, tópicos no Threads e outras. A lista completa por rede está em meta em Create post (veja o aviso sobre a referência no início desta página). Chaves que o PostClean não conhece são descartadas; configurações de outra rede são aceitas, mas não são usadas.

3. Crie o post

Create post cria um post em um canal: envie em platforms uma lista com exatamente um item, com o social_account_id do canal e, ao lado dele, o content_type e o meta. Sem status, o post é salvo como rascunho.

curl -X POST https://post.chatclean.com.br/api/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Our autumn collection is live.",
    "media": [
      { "url": "https://example.com/autumn.jpg", "alt": "Three jackets on a rail" }
    ],
    "platforms": [
      {
        "social_account_id": "2b7e4c19-8f3a-4d6b-9c1e-5a0f7d2b8e63",
        "content_type": "pinterest_pin",
        "meta": {
          "board_id": "1084231546543210987",
          "link": "https://example.com/autumn"
        }
      }
    ]
  }'

A resposta é o post (201), com status: "draft" e o canal em platforms: cada item traz id, platform, content_type, meta, status (o andamento na rede, começando em pending) e social_account. A mídia pode vir de uma URL, de um upload anterior ou de outro post; veja Envio de mídia.

Vários canais de uma vez

Para enviar o mesmo post a vários canais, use Create posts in batch. Ele cria um post independente por destino, todos com o mesmo post_group_id, igual a selecionar vários canais no app. Cada destino pode sobrescrever o content, a media, o content_type e o meta compartilhados. Aqui o status é obrigatório.

curl -X POST https://post.chatclean.com.br/api/posts/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "scheduled",
    "scheduled_at": "2026-10-12T14:00:00Z",
    "content": "Our autumn collection is live.",
    "media": [{ "url": "https://example.com/autumn.jpg" }],
    "destinations": [
      { "social_account_id": "9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54" },
      {
        "social_account_id": "5d1f8a27-3c6e-4b9d-a2f0-7e4c1b8d6a35",
        "content_type": "tiktok_photo",
        "meta": { "privacy_level": "PUBLIC_TO_EVERYONE" }
      }
    ]
  }'

A resposta é { "posts": [...] }, um post por destino. Um erro de validação interrompe a chamada inteira; os erros indicam o destino, por exemplo destinations.1.meta.privacy_level.

4. Agende, coloque na fila ou publique

O status decide o que acontece com o post. Envie-o na criação ou depois, com Update post:

`status`	Resultado
`draft`	Salvo e editável. Numa atualização, desfaz o agendamento de um post agendado (o último `scheduled_at` continua no rascunho)
`scheduled`	Publicado no `scheduled_at`, ou na fila do canal com `queue` / `queue_slot`
`publishing`	Publicado agora

Num horário definido

Envie status: scheduled com scheduled_at, um instante no futuro e antes de 2038-01-19. Informe-o em UTC (Z) ou com fuso.

{
  "status": "scheduled",
  "scheduled_at": "2026-10-12T14:00:00Z"
}

Na fila do canal

Quando o canal tem horários de publicação (has_posting_schedule: true), envie queue no lugar de scheduled_at:

next pega o primeiro horário livre do canal.
top pega o primeiro horário que não esteja ocupado por um post com horário definido e passa os posts da fila que estão atrás dele para o próximo horário livre.

{
  "status": "scheduled",
  "queue": "next"
}

Para ocupar um horário exato, envie queue_slot com um instante tirado de List free queue slots. Isso só funciona em Create post e falha com 422 quando o horário foi ocupado nesse meio-tempo. queue não pode ser combinado com scheduled_at nem com queue_slot. Quando você envia queue_slot, é ele que define o horário; não envie scheduled_at junto. Um post na fila mantém o horário dele. Para mudar a ordem, use Reorder queue ou Move post to queue slot; para mudar os horários, Update posting schedule (ele substitui a programação inteira: envie o timezone (obrigatório) e o posting_goal e o posting_schedule atuais para mantê-los, porque os valores omitidos são apagados). Para repetir um post agendado, veja Set post recurrence.

Outra alteração na mesma fila do canal pode estar rodando quando você chamar. Nesse caso a API responde 409; repita a requisição.

Agora

Envie status: publishing, na criação ou num rascunho ou post agendado que já existe:

curl -X PUT https://post.chatclean.com.br/api/posts/9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "status": "publishing" }'

A resposta volta com status: "publishing" enquanto a rede recebe o post. Depois ele passa a published ou failed. O lado da rede fica em platforms[].status (pending, publishing, retrying, pending_review, published, failed ou rejected); platforms[].platform_url leva ao post publicado e platforms[].error_message diz o que deu errado. Consulte Get post periodicamente ou inscreva um webhook em post.published e post.failed. Posts criados pela API são publicados direto: as chaves de API pertencem a administradores do workspace, então não há etapa de aprovação (veja Aprovações).

Respostas em fio

Posts no X, no Bluesky e no Mastodon podem levar até 24 respostas, publicadas uma embaixo da outra, abaixo do primeiro post. Envie-as em meta.thread_replies, cada uma como { "text", "media" }:

{
  "content": "1/ We rebuilt scheduling from scratch. Here is what changed.",
  "status": "scheduled",
  "queue": "next",
  "social_account_id": "9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54",
  "content_type": "x_post",
  "meta": {
    "thread_replies": [
      { "text": "2/ Every channel now has its own posting times." },
      {
        "text": "3/ Full changelog below.",
        "media": [{ "url": "https://example.com/changelog.png" }]
      }
    ]
  }
}

Uma resposta precisa de texto ou de mídia.
O texto de cada resposta precisa caber no limite da conta: 280 no X (25000 com posts longos), 300 no Bluesky e 500 no Mastodon. No Mastodon, o aviso de conteúdo (spoiler_text) se repete em cada resposta e entra na contagem.
A mídia de uma resposta pertence só a ela: até 4 itens, informados por url, id ou upload_token, seguindo as regras de mídia da rede.
Em Update post, thread_replies substitui a lista inteira.

Se a publicação parar no meio, as respostas já publicadas são mantidas, e uma nova tentativa continua da próxima, sem publicá-las de novo.

Limites de conteúdo

Os limites da rede são conferidos quando um post é agendado ou publicado; rascunhos podem passar deles. O teto de 25000 caracteres vale para todo post, inclusive rascunhos.

Texto por conta. O texto precisa caber no max_content_length da conta, medido no texto que a rede recebe. Uma conta do X com posts longos aceita 25000 caracteres; as outras contas do X aceitam 280. Um emoji conta como um caractere.
Hashtags no Instagram. O Instagram aceita no máximo 5 hashtags por post.
Stories não têm legenda. instagram_story e facebook_story não enviam texto, então o texto deles não é publicado nem medido, e o limite de hashtags não se aplica.
Mídia. Cada tipo de conteúdo tem suas próprias regras de quantidade, tamanho, duração e proporção de mídia, listadas por List content types e na página de cada rede, por exemplo Instagram, X ou TikTok.

Get post preview devolve o texto que o canal do post vai receber (sanitized_content), o tamanho dele e o limite da conta.

Edição, exclusão e erros

Update post altera só os campos que você envia. O canal é fixo (social_account_id é recusado); para publicar em outro lugar, crie um novo post. Envie as configurações como content_type e meta no nível de cima, ou em platforms, com o id do item de platforms do post. O meta é mesclado com as configurações salvas; envie null numa chave para apagá-la. Configurações booleanas não podem ser apagadas: envie true ou false.
Posts em publishing, published ou failed não podem ser editados nem excluídos: a API responde 422.
Delete post remove o post só do PostClean. Ele nunca apaga nada que já foi publicado numa rede.
Os erros de validação vêm com o campo como chave: platforms.0.meta.board_id, platforms.0.content_type, content, media em Create post e Update post; destinations.N.… em Create posts in batch.

Visão geral

Posts

Notas de posts

Aprovações

Recorrência

Mídia e uploads

Contas sociais

Canais

Ideias

Etapas de ideias

Análises

Etiquetas

Assinaturas

Workspace

Chaves de API

Webhooks

Repost

Plataforma

1. Liste as contas sociais

2. Confira os tipos de conteúdo

Configurações obrigatórias

3. Crie o post

Vários canais de uma vez

4. Agende, coloque na fila ou publique

Num horário definido

Na fila do canal

Agora

Respostas em fio

Limites de conteúdo

Edição, exclusão e erros

​1. Liste as contas sociais

​2. Confira os tipos de conteúdo

​Configurações obrigatórias

​3. Crie o post

​Vários canais de uma vez

​4. Agende, coloque na fila ou publique

​Num horário definido

​Na fila do canal

​Agora

​Respostas em fio

​Limites de conteúdo

​Edição, exclusão e erros

1. Liste as contas sociais

2. Confira os tipos de conteúdo

Configurações obrigatórias

3. Crie o post

Vários canais de uma vez

4. Agende, coloque na fila ou publique

Num horário definido

Na fila do canal

Agora

Respostas em fio

Limites de conteúdo

Edição, exclusão e erros