Criar post

Cria um post em uma conta social. A conta, o formato e as configurações da rede vão em platforms, que precisa ter exatamente um item. Para o mesmo texto em vários canais, use POST /posts/batch.

• status: draft (padrão) salva um rascunho.
• status: scheduled com scheduled_at agenda nesse horário; com queue (next ou top) ocupa um horário da grade do canal; com queue_slot ocupa exatamente esse horário livre (de GET /channels/{account}/queue/slots).
• status: publishing publica agora.

Sem platforms[0].content_type, o formato é 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.

Para agendar ou publicar, o post precisa das configurações obrigatórias da rede em platforms[0].meta (veja PlatformMeta) e de texto ou mídia. Erros de formato dos campos aparecem em platforms.0.* (por exemplo platforms.0.meta.board_id); as checagens feitas ao montar o post (configuração obrigatória, formato incompatível com a mídia, falta de texto ou mídia, conta repetida) aparecem em destinations.0.* (por exemplo destinations.0.meta.board_id, destinations.0.content).

A chave de API age como o usuário que a criou. Só admins do workspace criam chaves, e admins publicam direto, então o post não fica pending_approval.

Responde 409 quando a fila do canal está sendo alterada por outra requisição; tente de novo.

POST /posts

cURL

x_thread

curl --request POST \ --url https://post.chatclean.com.br/api/posts \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "content": "Agora dá para agendar fios no X. Veja como funciona.", "status": "scheduled", "scheduled_at": "2026-11-12T14:00:00Z", "media": [ { "url": "https://chatclean.com.br/imagens/lancamento.jpg", "alt": "Banner do lançamento" } ], "platforms": [ { "social_account_id": "9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54", "content_type": "x_post", "meta": { "thread_replies": [ { "text": "2/ As respostas saem logo abaixo do primeiro post." } ] } } ], "label_ids": [ "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f" ] } '

201

{
  "id": "9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41",
  "post_group_id": "9d3c1f29-e0a1-4b7c-8d2e-5f6a7b8c9d03",
  "author": {
    "id": "9b1e2d3c-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
    "name": "Ana Souza"
  },
  "content": "Agora dá para agendar fios no X. Veja como funciona.",
  "media": [
    {
      "id": "9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
      "path": "medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg",
      "url": "https://post.chatclean.com.br/storage/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg",
      "type": "image",
      "mime_type": "image/jpeg",
      "original_filename": "lancamento.jpg",
      "size": 482113,
      "meta": {
        "width": 1080,
        "height": 1350,
        "alt_text": "Banner do lançamento"
      }
    }
  ],
  "status": "scheduled",
  "schedule_mode": "custom",
  "scheduled_at": "2026-11-12 14:00:00",
  "published_at": null,
  "approval_requested_by": null,
  "approval_requested_at": null,
  "approved_by": null,
  "approved_at": null,
  "recurrence": null,
  "origin": "trypost",
  "platforms": [
    {
      "id": "9d3c1f2b-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "platform": "x",
      "content_type": "x_post",
      "meta": {
        "thread_replies": [
          {
            "text": "2/ As respostas saem logo abaixo do primeiro post.",
            "media": []
          }
        ]
      },
      "status": "pending",
      "enabled": true,
      "platform_url": null,
      "published_at": null,
      "error_message": null,
      "display_name": "PostClean",
      "display_username": "postclean",
      "display_avatar": "https://pbs.twimg.com/profile_images/1790000000000000000/avatar_400x400.jpg",
      "social_account": {
        "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
      }
    }
  ],
  "labels": [
    {
      "id": "9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "name": "Lançamento",
      "color": "#2563EB",
      "created_at": "2026-09-01 10:00:00",
      "updated_at": "2026-09-01 10:00:00"
    }
  ],
  "created_at": "2026-11-06 13:20:11",
  "updated_at": "2026-11-06 13:20:11"
}

Authorizations

Authorization · string · header · required

Chave de API do workspace, criada em Configurações > Chaves de API.

Body

application/json

platforms · object[] · required

O canal do post. Exatamente um item. Um social_account_id no nível de cima não é aceito.

Required array length: 1 element

Show child attributes

content · string | null

Texto do post, até 25000 caracteres. Com status scheduled ou publishing, também precisa caber no limite da conta (max_content_length da conta social: 280 no X, 25000 em contas do X com posts longos, 300 no Bluesky, 500 no Mastodon contando o aviso de conteúdo), medido no texto que a rede recebe. Um post agendado ou publicado precisa de texto ou mídia.

Maximum string length: 25000

media · object[]

Mídias em ordem. Cada item traz exatamente um entre upload_token, url ou id. Tipos que a rede do canal não aceita são recusados.

Show child attributes

status · enum<string> · default: draft

draft salva um rascunho editável. scheduled agenda em scheduled_at ou na fila do canal (queue). publishing publica agora.

Available options: draft, scheduled, publishing

scheduled_at · string<date-time> | null

Quando publicar, com status: scheduled. Aceita qualquer data reconhecível; precisa estar no futuro e antes de 2038-01-19. Obrigatório com status: scheduled, a não ser que vá queue ou queue_slot. Não combina com queue.

queue · enum<string> | null

Posição na fila, só com status: scheduled. next pega o primeiro horário livre do canal; top pega o primeiro horário e empurra os posts da fila que estão atrás dele para a próxima lacuna. O canal precisa ter horários de postagem (has_posting_schedule). Não combina com scheduled_at.

Available options: next, top, null

queue_slot · string<date-time> | null

Instante de um horário livre de GET /channels/{account}/queue/slots, só com status: scheduled. Guarda o post na fila exatamente nesse horário; é recusado (422 em queue_slot) se o horário já estiver ocupado ou reservado por um pedido de aprovação. Antes de 2038-01-19. Não combina com queue. Se vier junto com scheduled_at, vale o queue_slot.

label_ids · string<uuid>[]

Etiquetas deste workspace.

Response

201

application/json

O post criado.

Um post em um canal. Posts criados juntos para vários canais são posts independentes que compartilham o mesmo post_group_id. O canal, o formato, as configurações da rede e o resultado da publicação ficam em platforms.

id · string<uuid>

post_group_id · string<uuid> | null

Igual em todos os posts criados na mesma requisição.

author · object | null

Um membro do workspace. Só o id e o nome são expostos.

Show child attributes

content · string | null

Texto do post, guardado como foi enviado (posts escritos no app guardam o HTML do editor).

media · object[] | null

Show child attributes

status · enum<string>

Ciclo de vida do post no PostClean. pending_approval é um post que um membro que precisa de aprovação pediu para agendar ou publicar. partially_published aparece em posts antigos com vários destinos quando só parte deles foi publicada. O resultado em cada rede fica em platforms[].status.

Available options: draft, pending_approval, scheduled, publishing, published, partially_published, failed

schedule_mode · enum<string> | null

queue: o post ocupa um horário da grade de postagem do canal. custom: está agendado num horário próprio.

Available options: queue, custom, null

scheduled_at · string | null

UTC, no formato Y-m-d H:i:s.

published_at · string | null

UTC, no formato Y-m-d H:i:s.

approval_requested_by · object | null

Quem pediu a aprovação (nem sempre é o autor).

Show child attributes

approval_requested_at · string | null

UTC, no formato Y-m-d H:i:s.

approved_by · object | null

Um membro do workspace. Só o id e o nome são expostos.

Show child attributes

approved_at · string | null

UTC, no formato Y-m-d H:i:s.

recurrence · object | null

Regra de repetição, ou null.

Show child attributes

origin · enum<string>

trypost para posts criados no PostClean. network para posts importados da rede (publicados fora do PostClean).

Available options: trypost, network

platforms · object[]

Destinos do post. Posts criados pela API têm exatamente um.

Show child attributes

labels · object[]

Show child attributes

created_at · string

UTC, no formato Y-m-d H:i:s.

updated_at · string

UTC, no formato Y-m-d H:i:s.