> ## Documentation Index > Fetch the complete documentation index at: https://docs.postclean.com.br/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /posts openapi: 3.1.0 info: title: PostClean API version: 2.0.0 description: >- API REST do PostClean. Autentique com uma chave de API do workspace, enviada como token Bearer no cabeçalho `Authorization`. servers: - url: https://post.chatclean.com.br/api description: PostClean security: - bearerAuth: [] tags: - name: Posts description: Criar, ler, atualizar, excluir e pré-visualizar posts. - name: Post notes description: Notas internas de um post, visíveis aos membros do workspace. - name: Approvals description: Aprovar ou rejeitar posts que aguardam aprovação. - name: Recurrence description: Fazer um post se repetir numa frequência. - name: Media and uploads description: Enviar arquivos e anexar mídia aos posts. - name: Social accounts description: Contas sociais conectadas e as opções de cada rede. - name: Channels description: Horários de postagem e fila de um canal. - name: Ideas description: Ideias do quadro Criar. - name: Idea stages description: As colunas (etapas) do quadro de ideias. - name: Analytics description: Métricas do workspace e dos canais. - name: Labels description: Etiquetas para organizar posts e ideias. - name: Signatures description: Textos reutilizáveis para adicionar aos posts. - name: Workspace description: O workspace ao qual a chave de API pertence. - name: API keys description: Chaves de API pessoais deste workspace. - name: Webhooks description: Webhooks de saída e os registros de entrega. - name: Repurposes description: Automações que republicam vídeos postados fora do PostClean. - name: Platform description: Recursos de cada plataforma e tipos de conteúdo. paths: /posts: post: tags: - Posts summary: Criar post description: >- 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. operationId: createPost requestBody: required: true content: application/json: schema: type: object required: - platforms properties: content: type: - string - 'null' maxLength: 25000 description: >- 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. media: type: array items: $ref: '#/components/schemas/MediaReference' description: >- 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. status: type: string enum: - draft - scheduled - publishing description: >- `draft` salva um rascunho editável. `scheduled` agenda em `scheduled_at` ou na fila do canal (`queue`). `publishing` publica agora. default: draft platforms: type: array minItems: 1 maxItems: 1 description: >- O canal do post. Exatamente um item. Um `social_account_id` no nível de cima não é aceito. items: type: object required: - social_account_id properties: social_account_id: type: string format: uuid description: Conta social deste workspace. content_type: oneOf: - $ref: '#/components/schemas/ContentType' - type: 'null' description: >- Formato; precisa ser da rede da conta. Sem ele, é escolhido pela mídia. meta: $ref: '#/components/schemas/PlatformMeta' scheduled_at: type: - string - 'null' format: date-time description: >- 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: type: - string - 'null' enum: - next - top - null description: >- 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`. queue_slot: type: - string - 'null' format: date-time description: >- 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: type: array items: type: string format: uuid description: Etiquetas deste workspace. examples: x_thread: summary: Fio no X com imagem, em horário próprio value: 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 pinterest_queue: summary: Pin no Pinterest na fila do canal value: content: Tudo o que lançamos em novembro, num pin só. status: scheduled queue: next media: - upload_token: 4f6c2b1e-8d3a-4e5f-9a7b-1c2d3e4f5a6b alt: Capa das novidades platforms: - social_account_id: 9c8b7a65-5e4f-4a3b-9c2d-1e0f9a8b7c65 meta: board_id: '1022106146620830917' title: Novidades de novembro link: https://chatclean.com.br/blog draft: summary: Rascunho só com texto value: content: Ideia para a semana que vem. platforms: - social_account_id: 9c8b7a65-4d3e-4f2a-8b1c-0d9e8f7a6b54 responses: '201': description: O post criado. content: application/json: schema: $ref: '#/components/schemas/Post' example: 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' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: MediaReference: type: object description: >- Um item de mídia para colocar num post. Informe **exatamente um** entre `upload_token`, `url` e `id`; caso contrário o pedido falha com `Each media item needs exactly one of upload_token, url or id.` properties: upload_token: type: string format: uuid description: >- Token de `POST /uploads` ou de uma URL assinada. Uso único: o primeiro post que o recebe o consome. Vale 24 horas. url: type: string format: uri maxLength: 2048 description: >- URL pública `http` ou `https` do próprio arquivo. É baixada uma vez por pedido; redirecionamentos não são seguidos e hosts privados são recusados. id: type: string format: uuid description: >- Id de uma mídia que já está neste workspace (por exemplo o `media[].id` de outro post). O arquivo é copiado. alt: type: - string - 'null' maxLength: 2000 description: >- Atalho para o texto alternativo. Vale só para imagens; `meta.alt_text` prevalece quando os dois são enviados. meta: $ref: '#/components/schemas/MediaItemMeta' examples: - url: https://example.com/lancamento.jpg alt: Banner de lançamento do produto ContentType: type: string enum: - instagram_feed - instagram_reel - instagram_story - linkedin_post - linkedin_page_post - facebook_post - facebook_reel - facebook_story - tiktok_video - tiktok_photo - youtube_short - x_post - threads_post - threads_ghost_post - pinterest_pin - pinterest_video_pin - pinterest_carousel - bluesky_post - mastodon_post - telegram_post - discord_message - google_business_post description: >- Formato do post numa rede. Precisa pertencer à rede do destino. `GET /content-types` lista os formatos de cada rede com as regras de mídia. Stories do Instagram e do Facebook não publicam texto. PlatformMeta: description: >- Configurações por rede de um destino. Use o formato da rede do destino. Chaves sem regra são descartadas. Toda chave conhecida é validada qualquer que seja a rede, mas só as chaves da rede do destino são usadas na publicação. Na atualização, `meta` é mesclado com as configurações salvas: envie `null` numa chave para limpá-la (vale para textos, listas e objetos; booleanos não podem ser limpos, então envie `true` ou `false`), e `thread_replies` substitui a lista inteira. Obrigatório para agendar ou publicar: `privacy_level` no TikTok, `board_id` no Pinterest, `channel_id` no Discord, `event` no Google Business em `EVENT` e `OFFER` e, no YouTube, um título (`title` ou a primeira linha do texto). `GET /content-types` lista em `required_meta` os obrigatórios incondicionais de cada rede (TikTok, Pinterest e Discord). anyOf: - $ref: '#/components/schemas/PlatformMetaX' - $ref: '#/components/schemas/PlatformMetaBluesky' - $ref: '#/components/schemas/PlatformMetaMastodon' - $ref: '#/components/schemas/PlatformMetaTikTok' - $ref: '#/components/schemas/PlatformMetaPinterest' - $ref: '#/components/schemas/PlatformMetaDiscord' - $ref: '#/components/schemas/PlatformMetaYouTube' - $ref: '#/components/schemas/PlatformMetaInstagram' - $ref: '#/components/schemas/PlatformMetaThreads' - $ref: '#/components/schemas/PlatformMetaFacebook' - $ref: '#/components/schemas/PlatformMetaLinkedIn' - $ref: '#/components/schemas/PlatformMetaGoogleBusiness' - $ref: '#/components/schemas/PlatformMetaNone' Post: type: object description: >- 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`. properties: id: type: string format: uuid post_group_id: type: - string - 'null' format: uuid description: Igual em todos os posts criados na mesma requisição. author: oneOf: - $ref: '#/components/schemas/Person' - type: 'null' content: type: - string - 'null' description: >- Texto do post, guardado como foi enviado (posts escritos no app guardam o HTML do editor). media: type: - array - 'null' items: $ref: '#/components/schemas/MediaItem' status: type: string enum: - draft - pending_approval - scheduled - publishing - published - partially_published - failed description: >- 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`. schedule_mode: type: - string - 'null' enum: - queue - custom - null description: >- `queue`: o post ocupa um horário da grade de postagem do canal. `custom`: está agendado num horário próprio. scheduled_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. published_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. approval_requested_by: oneOf: - $ref: '#/components/schemas/Person' - type: 'null' description: Quem pediu a aprovação (nem sempre é o autor). approval_requested_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. approved_by: oneOf: - $ref: '#/components/schemas/Person' - type: 'null' approved_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. recurrence: type: - object - 'null' description: Regra de repetição, ou `null`. properties: interval: type: integer frequency: type: string enum: - day - week - month - year remaining: type: - integer - 'null' description: Quantas repetições ainda faltam depois da ocorrência atual. origin: type: string enum: - trypost - network description: >- `trypost` para posts criados no PostClean. `network` para posts importados da rede (publicados fora do PostClean). platforms: type: array items: $ref: '#/components/schemas/PostPlatform' description: Destinos do post. Posts criados pela API têm exatamente um. labels: type: array items: $ref: '#/components/schemas/Label' created_at: type: string description: UTC, no formato `Y-m-d H:i:s`. updated_at: type: string description: UTC, no formato `Y-m-d H:i:s`. examples: - 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' MediaItemMeta: type: object description: >- Configurações editáveis de um item de mídia. As respostas também podem trazer chaves medidas pelo servidor (por exemplo `width`, `height` e `duration`). properties: alt_text: type: string maxLength: 2000 description: >- Descrição de acessibilidade. Vale para imagens; cada rede corta no próprio limite. user_tags: type: array maxItems: 20 description: Pessoas marcadas numa imagem do Instagram (só `instagram_feed`). items: type: object required: - username - x - 'y' properties: username: type: string pattern: ^@?[A-Za-z0-9._]{1,30}$ description: >- Nome de usuário público do Instagram. Um `@` no início é removido. x: type: number minimum: 0 maximum: 1 description: Distância da borda esquerda, de 0 a 1. 'y': type: number minimum: 0 maximum: 1 description: Distância da borda de cima, de 0 a 1. cover_offset_ms: type: integer minimum: 0 description: >- Quadro do vídeo usado como capa, em milissegundos a partir do início. Não pode passar do fim do vídeo. PlatformMetaX: type: object title: X description: Configurações de `x_post`. properties: thread_replies: type: - array - 'null' maxItems: 24 description: >- Até 24 respostas publicadas abaixo do post, formando uma sequência. Cada item é um `ThreadReply` ou uma string simples para uma resposta só de texto. Na atualização, esta lista substitui a salva. items: oneOf: - type: string maxLength: 25000 title: Resposta só de texto - $ref: '#/components/schemas/ThreadReply' is_ai_generated: type: boolean description: >- Informa que a mídia do post foi gerada por IA (enviado ao X como `made_with_ai`). PlatformMetaBluesky: type: object title: Bluesky description: Configurações de `bluesky_post`. properties: thread_replies: type: - array - 'null' maxItems: 24 description: >- Até 24 respostas publicadas abaixo do post, formando uma sequência. Cada item é um `ThreadReply` ou uma string simples para uma resposta só de texto. Na atualização, esta lista substitui a salva. items: oneOf: - type: string maxLength: 25000 title: Resposta só de texto - $ref: '#/components/schemas/ThreadReply' link_preview: type: boolean default: true description: >- Envie `false` (um booleano de verdade, não a string) para publicar um post de texto com link sem o cartão de prévia. PlatformMetaMastodon: type: object title: Mastodon description: Configurações de `mastodon_post`. properties: thread_replies: type: - array - 'null' maxItems: 24 description: >- Até 24 respostas publicadas abaixo do post, formando uma sequência. Cada item é um `ThreadReply` ou uma string simples para uma resposta só de texto. Na atualização, esta lista substitui a salva. items: oneOf: - type: string maxLength: 25000 title: Resposta só de texto - $ref: '#/components/schemas/ThreadReply' spoiler_text: type: - string - 'null' maxLength: 500 description: Aviso de conteúdo. Conta no limite de 500 caracteres do post. PlatformMetaTikTok: type: object title: TikTok description: >- Configurações de `tiktok_video` e `tiktok_photo`. `privacy_level` é obrigatório para agendar ou publicar; leia os valores permitidos em `GET /social-accounts/{account}/tiktok-creator-info` e mantenha `allow_comments`, `allow_duet` e `allow_stitch` como `false` quando ele os informar desativados. `SELF_ONLY` não pode ser usado junto com `brand_content_toggle`. properties: privacy_level: type: - string - 'null' enum: - PUBLIC_TO_EVERYONE - MUTUAL_FOLLOW_FRIENDS - FOLLOWER_OF_CREATOR - SELF_ONLY - null description: Quem pode ver o post. Obrigatório para agendar ou publicar. allow_comments: type: boolean description: Permite comentários. allow_duet: type: boolean description: Permite dueto. Só `tiktok_video`. allow_stitch: type: boolean description: Permite costura (stitch). Só `tiktok_video`. is_aigc: type: boolean description: Selo de conteúdo gerado por IA. Só `tiktok_video`. auto_add_music: type: boolean description: Adiciona música automaticamente. Só `tiktok_photo`. disclose: type: boolean description: Declaração de conteúdo comercial. brand_content_toggle: type: boolean description: Parceria paga. brand_organic_toggle: type: boolean description: Divulga a sua própria marca. PlatformMetaPinterest: type: object title: Pinterest description: >- Configurações de `pinterest_pin`, `pinterest_video_pin` e `pinterest_carousel`. A descrição do pin é o texto do post; a capa de um pin de vídeo é o `meta.cover_offset_ms` do item de mídia. properties: board_id: type: - string - 'null' description: >- Pasta onde o pin será salvo. Obrigatório para agendar ou publicar. Liste as pastas com `GET /social-accounts/{account}/boards` ou crie uma com `POST /social-accounts/{account}/boards`. title: type: - string - 'null' maxLength: 100 description: Título do pin. link: type: - string - 'null' format: uri maxLength: 2048 description: URL de destino (`http` ou `https`). PlatformMetaDiscord: type: object title: Discord description: Configurações de `discord_message`. properties: channel_id: type: - string - 'null' description: >- Canal onde a mensagem será enviada. Obrigatório para agendar ou publicar. Liste os canais com `GET /social-accounts/{account}/channels`. channel_name: type: - string - 'null' description: >- Nome do canal mostrado no app. É salvo como enviado; o PostClean não o confere com `channel_id`. mentions: type: - array - 'null' items: type: object required: - token properties: token: type: string description: Token da menção, por exemplo `@everyone` ou `<@&roleId>`. label: type: - string - 'null' description: Rótulo mostrado no app. description: Menções incluídas na mensagem. embeds: type: - array - 'null' maxItems: 10 items: type: object properties: title: type: - string - 'null' maxLength: 256 description: Título do embed. description: type: - string - 'null' maxLength: 4096 description: Texto do embed. url: type: - string - 'null' format: uri description: Link do título. image: type: - string - 'null' format: uri description: URL da imagem. color: type: - string - 'null' pattern: ^#?[0-9A-Fa-f]{6}$ description: Cor em hexadecimal, `#RRGGBB`. description: Até 10 embeds. PlatformMetaYouTube: type: object title: YouTube description: >- Configurações de `youtube_short`. Para agendar ou publicar, o post precisa de `title` ou de texto. properties: title: type: - string - 'null' maxLength: 100 description: >- Sem `<` nem `>` (recusado até em rascunhos). Se omitido, vira a primeira linha não vazia do texto, sem `<` e `>`, cortada em 100 caracteres. description: type: - string - 'null' description: >- Texto simples, no máximo 5000 bytes. Omita ou envie `null` para usar o texto do post. category_id: type: - string - 'null' enum: - '1' - '2' - '10' - '15' - '17' - '19' - '20' - '22' - '23' - '24' - '25' - '26' - '27' - '28' - '29' - null default: '22' description: >- Categoria do YouTube: 1 Filmes e animação, 2 Autos e veículos, 10 Música, 15 Animais de estimação, 17 Esportes, 19 Viagens e eventos, 20 Jogos, 22 Pessoas e blogs, 23 Comédia, 24 Entretenimento, 25 Notícias e política, 26 Guias e estilo, 27 Educação, 28 Ciência e tecnologia, 29 ONGs e ativismo. Um id inteiro é aceito e salvo como string. privacy_status: type: - string - 'null' enum: - public - unlisted - private - null default: public description: Visibilidade do vídeo. license: type: - string - 'null' enum: - youtube - creativeCommon - null default: youtube description: Licença do vídeo. notify_subscribers: type: boolean default: true description: Avisa os inscritos. embeddable: type: boolean default: true description: Permite incorporar o vídeo em outros sites. made_for_kids: type: boolean default: false description: Conteúdo feito para crianças. is_ai_generated: type: boolean description: Informa conteúdo alterado ou sintético. PlatformMetaInstagram: type: object title: Instagram description: >- Configurações de `instagram_feed`, `instagram_reel` e `instagram_story` (contas `instagram` e `instagram-facebook`). Um `instagram_feed` com um único vídeo é publicado como Reel. As pessoas marcadas ficam em `meta.user_tags` do item de mídia, e a capa de um vídeo em `meta.cover_offset_ms`. Um post pode ter no máximo 5 hashtags. properties: is_ai_generated: type: boolean description: Selo de conteúdo gerado por IA (feed, reels, stories e carrosséis). share_to_feed: type: boolean default: true description: 'Só `instagram_reel`: mostra o Reel também no feed do perfil.' PlatformMetaThreads: type: object title: Threads description: >- Configurações de `threads_post`. Use o tipo `threads_ghost_post` para um post só de texto arquivado depois de 24 horas (sem mídia e sem tópico). properties: topic_tag: type: - string - 'null' description: >- Tópico, de 1 a 50 caracteres depois de remover um `#` no início, sem `.` nem `&`. PlatformMetaFacebook: type: object title: Facebook description: >- Configurações de `facebook_post`. Reels e stories do Facebook não têm configurações; stories não publicam texto. properties: link_preview: type: boolean default: true description: >- Envie `false` (um booleano de verdade, não a string) para publicar um post de texto com link sem o cartão de prévia. PlatformMetaLinkedIn: type: object title: LinkedIn description: >- Configurações de `linkedin_post` e `linkedin_page_post`. O LinkedIn não aceita `thread_replies`. properties: link_preview: type: boolean default: true description: >- Envie `false` (um booleano de verdade, não a string) para publicar um post de texto com link sem o cartão de prévia. document_title: type: - string - 'null' maxLength: 300 description: >- Título mostrado num post de documento PDF. Padrão: o nome do arquivo. PlatformMetaGoogleBusiness: type: object title: Google Business Profile description: >- Configurações de `google_business_post`. Um `EVENT` ou `OFFER` precisa de `event.title`, `event.start_date` e `event.end_date` (na oferta, o título é o da oferta) e não pode terminar antes de começar. properties: topic_type: type: - string - 'null' enum: - STANDARD - EVENT - OFFER - null default: STANDARD description: Tipo do post. call_to_action: type: - object - 'null' description: Botão do post. Não vale em `OFFER`. properties: action_type: type: - string - 'null' enum: - NONE - BOOK - ORDER - SHOP - LEARN_MORE - SIGN_UP - CALL - null description: Ação do botão. url: type: - string - 'null' format: uri maxLength: 2048 description: Obrigatória, exceto quando `action_type` é `NONE` ou `CALL`. event: type: - object - 'null' description: Obrigatório em `EVENT` e `OFFER`. properties: title: type: - string - 'null' maxLength: 58 description: Título do evento ou da oferta. start_date: type: - string - 'null' format: date description: '`AAAA-MM-DD`.' end_date: type: - string - 'null' format: date description: '`AAAA-MM-DD`, não antes de `start_date`.' start_time: type: - string - 'null' pattern: ^\d{2}:\d{2}$ description: '`HH:MM`.' end_time: type: - string - 'null' pattern: ^\d{2}:\d{2}$ description: '`HH:MM`. No mesmo dia, não antes de `start_time`.' offer: type: - object - 'null' description: Só `OFFER`. properties: coupon_code: type: - string - 'null' description: Código do cupom. redeem_online_url: type: - string - 'null' format: uri maxLength: 2048 description: Link para resgatar a oferta. terms_conditions: type: - string - 'null' maxLength: 5000 description: Termos e condições. PlatformMetaNone: type: object title: Telegram description: Telegram (e reels e stories do Facebook) não têm configurações. properties: {} Person: type: object description: Um membro do workspace. Só o id e o nome são expostos. properties: id: type: string format: uuid name: type: string MediaItem: type: object description: Um item de mídia como fica salvo no post. properties: id: type: string format: uuid description: >- Id da mídia. Passe como `media[].id` para usar o arquivo em outro post. path: type: string description: Caminho no armazenamento, `medias/{uuid}.{ext}`. url: type: string format: uri description: URL pública do arquivo. type: type: - string - 'null' enum: - image - video - document - null description: '`null` em itens antigos, salvos sem tipo.' mime_type: type: - string - 'null' description: Tipo MIME do arquivo. original_filename: type: - string - 'null' description: Nome original do arquivo. size: type: - integer - 'null' description: Tamanho em bytes. meta: $ref: '#/components/schemas/MediaItemMeta' source: type: - string - 'null' enum: - ai - unsplash - google_drive - google_photos - canva - null description: >- De onde o arquivo veio no app. Só aparece em itens adicionados por uma dessas fontes. source_meta: type: - object - 'null' description: Detalhes dessa fonte. Só aparece quando a fonte informou algum. examples: - id: 9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f path: medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg url: https://example.com/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 de lançamento do produto PostPlatform: type: object description: >- O destino de um post: o canal (conta social) onde ele é publicado, com o formato, as configurações da rede e o resultado da publicação. Posts criados pela API têm um único destino; posts antigos, criados antes de os posts ficarem independentes, podem ter vários. properties: id: type: string format: uuid description: Id do destino. É o `platforms[].id` aceito por `PUT /posts/{post}`. platform: oneOf: - $ref: '#/components/schemas/Platform' - type: 'null' description: Rede do canal. content_type: oneOf: - $ref: '#/components/schemas/ContentType' - type: 'null' meta: type: - object - array - 'null' description: >- Configurações da rede salvas para este destino (veja `PlatformMeta`). Sem configurações, pode vir como lista vazia (`[]`). status: type: - string - 'null' enum: - pending - publishing - retrying - pending_review - published - failed - rejected - null description: >- Estado da publicação na rede. `pending` até o post ser enviado; `retrying` aguarda nova tentativa depois de um limite ou de uma falha temporária da rede; `pending_review` e `rejected` vêm de redes que revisam os posts (Google Business). enabled: type: boolean description: Se o destino está ativo. Destinos desativados não são publicados. platform_url: type: - string - 'null' description: Link do post publicado na rede. published_at: type: - string - 'null' description: UTC, no formato `Y-m-d H:i:s`. error_message: type: - string - 'null' description: Motivo da falha na publicação, quando houve. display_name: type: - string - 'null' description: >- Nome da conta. Continua aqui mesmo depois que a conta é desconectada. display_username: type: - string - 'null' display_avatar: type: - string - 'null' social_account: oneOf: - $ref: '#/components/schemas/SocialAccount' - type: 'null' description: >- A conta social, ou `null` quando ela já foi removida (os campos `display_*` guardam o nome). Label: type: object properties: id: type: string format: uuid name: type: string color: type: string description: Cor em hexadecimal, `#RRGGBB`. examples: - '#2563EB' created_at: type: string description: Em UTC, no formato `Y-m-d H:i:s`. examples: - '2026-09-01 10:00:00' updated_at: type: string description: Em UTC, no formato `Y-m-d H:i:s`. examples: - '2026-09-01 10:00:00' ErrorBody: type: object properties: message: type: string description: Corpo de erro com uma mensagem. ValidationErrorBody: type: object properties: message: type: string errors: type: object additionalProperties: type: array items: type: string description: Corpo de erro de validação. `errors` traz as mensagens por campo. RateLimitErrorBody: type: object properties: name: type: string const: rate_limit_exceeded message: type: string examples: - Rate limit exceeded. Please retry after 30 seconds. description: Corpo devolvido quando o limite de requisições é excedido. ThreadReply: type: object description: >- Uma resposta publicada abaixo do post, formando uma sequência (X, Bluesky e Mastodon). Uma resposta precisa de texto ou de mídia. O texto precisa caber no limite da conta (Bluesky 300, Mastodon 500 contando o aviso de conteúdo, que se repete em cada resposta, X 280 ou 25000 para contas com posts longos). As mídias pertencem só a esta resposta e seguem as regras de mídia de um post nessa rede. Em outras redes, agendar ou publicar com `thread_replies` falha com `Threads of posts are not available on this network.` properties: text: type: - string - 'null' maxLength: 25000 description: Texto da resposta. media: type: - array - 'null' maxItems: 4 description: >- Até 4 itens de mídia, cada um dado por `url`, `id` ou `upload_token`, com `meta.alt_text` opcional. items: $ref: '#/components/schemas/MediaReference' examples: - text: 3/ O changelog completo está abaixo. media: - url: https://example.com/changelog.png Platform: type: string enum: - linkedin - linkedin-page - x - tiktok - youtube - facebook - instagram - instagram-facebook - threads - pinterest - bluesky - mastodon - telegram - discord - google_business description: >- Rede de uma conta social. `linkedin-page` é uma página de empresa no LinkedIn, e `instagram-facebook` é uma conta do Instagram conectada por uma Página do Facebook. SocialAccount: type: object properties: id: type: string format: uuid platform: $ref: '#/components/schemas/Platform' display_name: type: - string - 'null' description: Nome exibido da conta. username: type: - string - 'null' description: Nome de usuário na rede. status: type: string enum: - connected - disconnected - token_expired description: >- Status da conexão. `token_expired` e `disconnected` pedem reconexão no app. has_posting_schedule: type: boolean description: >- Se o canal tem horários de postagem. Colocar um post na fila (`queue`) exige horários. timezone: type: string description: >- Fuso horário IANA do canal. Os horários da fila e a recorrência seguem esse fuso. posting_goal: type: - integer - 'null' description: Meta de posts por semana do canal. max_content_length: type: integer description: >- Limite de texto desta conta, em caracteres. Uma conta do X com posts longos tem 25000. long_posts: type: boolean description: Se esta conta do X pode publicar posts longos. verified_badge: type: - string - 'null' enum: - blue - business - government - null description: >- Selo de verificação do X; `null` em outras redes ou em contas sem verificação. O selo sozinho não garante posts longos: veja `long_posts`. responses: Unauthorized: description: >- Chave de API ausente, inválida, revogada ou expirada. Corpos possíveis: `Unauthenticated.` (sem chave, ou chave inválida ou revogada), `Token expired.` (passou do `expires_at`), `Token not found.` e `No workspace selected.` (a chave não está mais ligada a um workspace). content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: message: Unauthenticated. PaymentRequired: description: >- A conta do workspace não tem assinatura ativa nem período de teste. Corpo: `{"message": "Active subscription required."}`. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: message: Active subscription required. Forbidden: description: >- A requisição não é permitida. Chaves de API só funcionam para administradores do workspace (o dono da conta ou um membro marcado como administrador); fora isso, toda requisição devolve `Insufficient workspace permissions.`. Outros corpos: `Workspace access denied.` (o usuário da chave saiu do workspace), `Personal access token required.` (foi enviado um token OAuth do MCP) e `This action is unauthorized.` (por exemplo, a nota pertence a outro membro). content: application/json: schema: $ref: '#/components/schemas/ErrorBody' Conflict: description: >- Outra alteração neste post ou na fila do canal está em andamento. Tente de novo. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' ValidationError: description: A validação falhou. Cada campo com erro aparece em `errors`. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorBody' TooManyRequests: description: 'Limite de requisições excedido: 60 por minuto por workspace.' headers: Retry-After: description: Segundos de espera antes de tentar de novo. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorBody' example: name: rate_limit_exceeded message: Rate limit exceeded. Please retry after 30 seconds. securitySchemes: bearerAuth: type: http scheme: bearer description: Chave de API do workspace, criada em Configurações > Chaves de API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.