Introdução

Autentique com uma chave de API do workspace e chame a API REST do PostClean: URL base, permissões, erros, paginação e limites de requisições.

A API REST do PostClean permite que scripts e integrações façam o que você faz no app: criar, agendar e publicar posts, enviar mídia, gerenciar as filas e os horários de publicação dos canais, ideias, etiquetas, assinaturas, webhooks e reposts, e ler as análises.

​

URL base

https://post.chatclean.com.br/api

​

Autenticação

Toda requisição envia uma chave de API do workspace como token Bearer no cabeçalho Authorization:

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

Envie sempre Accept: application/json, como em todos os exemplos destas páginas. Sem ele, alguns erros (por exemplo, o 409 de uma fila de canal ocupada) voltam como redirecionamento em vez de um corpo JSON.

Crie uma chave no app em Configurações → API Keys → Gerar chave API (veja Chaves de API) ou com Criar chave de API. A chave aparece uma única vez, quando é criada. Guarde-a na hora; se você perdê-la, gere uma nova.

Trate a chave de API como uma senha. Não a coloque em código que roda no navegador nem a envie para um repositório.

As chaves de API autenticam apenas a API REST. O servidor MCP usa login com OAuth, e um token MCP enviado à API REST é recusado com 403 Personal access token required..

​

Quem pode usar chaves de API

As chaves de API funcionam só para administradores do workspace: o dono da conta e os membros marcados como administradores. Quando o dono da chave não é administrador do workspace, toda requisição retorna 403 com Insufficient workspace permissions.; quando ele saiu do workspace, 403 com Workspace access denied.. Veja Membros e permissões.

​

Uma chave, um workspace

A chave fica presa ao workspace em que foi criada. Toda requisição age nesse workspace, qualquer que seja o workspace aberto no app, e recursos de outros workspaces respondem 404. Para automatizar vários workspaces, crie uma chave em cada um.

​

Aprovações

Administradores publicam direto, então um post criado ou editado pela API nunca fica esperando aprovação: status: scheduled agenda o post e status: publishing publica na hora.

Membros que precisam de aprovação continuam enviando pedidos pelo app e pelo servidor MCP. Esses posts aparecem na API com status: pending_approval, e você pode decidi-los com Aprovar post e Rejeitar post. Ver workspace devolve as suas próprias permissões em me (is_admin, requires_approval, publishes_directly).

​

Assinatura

A conta dona do workspace precisa de uma assinatura ativa ou de um período de teste. Sem isso, toda requisição retorna 402:

{
  "message": "Active subscription required."
}

​

Recursos de IA

As ferramentas de escrita e de imagem com IA existem só no app web. A API não tem endpoint de IA, e criar um post pela API nunca chama a IA. Um repost pode encurtar com IA uma legenda longa demais para um destino (veja Criar repurpose).

​

Limites de requisições

Cada workspace pode fazer 60 requisições por minuto. Todas as chaves do workspace dividem esse limite. As respostas trazem X-RateLimit-Limit e X-RateLimit-Remaining.

Quatro chamadas que consultam a rede social diretamente também contam para um segundo limite de 60 requisições por minuto por usuário, dividido entre as quatro e entre todos os seus workspaces: Listar pastas do Pinterest, Criar pasta do Pinterest, Listar canais do Discord e Ver dados de criador do TikTok.

Acima do limite, a API responde 429 com o cabeçalho Retry-After (segundos de espera):

{
  "name": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please retry after 30 seconds."
}

​

Erros

A API usa os códigos de status HTTP padrão e sempre responde em JSON com um message.

Status	Significado
200	Sucesso
201	Criado
204	Sucesso sem corpo (exclusões, exceto Remover repetição do post, e reordenação da fila)
401	Chave de API ausente, inválida ou expirada (Token expired.)
402	Sem assinatura ativa (Active subscription required.)
403	Não permitido: o dono da chave não é administrador do workspace (Insufficient workspace permissions.), ou a ação não é permitida para esse recurso
404	O recurso não existe neste workspace
409	Outra alteração no mesmo post ou na mesma fila de canal está em andamento. Repita a requisição
422	A validação falhou, ou a ação não combina com o estado do recurso (por exemplo, editar ou excluir um post que já foi enviado)
429	Limite de requisições excedido

Os erros de validação listam as mensagens de cada campo em errors, com o caminho do campo como chave:

{
  "message": "Selecione um quadro do Pinterest para publicar este post.",
  "errors": {
    "destinations.0.meta.board_id": [
      "Selecione um quadro do Pinterest para publicar este post."
    ]
  }
}

Em Criar post, o formato dos campos do canal é conferido dentro de platforms (platforms.0.content_type, platforms.0.meta.board_id) e os demais campos usam o próprio nome (content, media). As checagens feitas ao montar o post, como uma configuração obrigatória da rede que ficou faltando, voltam em destinations.0.*, como no exemplo acima. Em Criar posts em lote, o número indica o destino: destinations.1.meta.privacy_level.

As mensagens de validação seguem o idioma do servidor, português no PostClean. As mensagens de autenticação, permissão e assinatura (Unauthenticated., Insufficient workspace permissions., Active subscription required.) e a de limite de requisições são fixas em inglês.

Os demais erros trazem só message:

{
  "message": "Insufficient workspace permissions."
}

​

Formato das respostas

Um recurso único volta como um objeto simples, sem o invólucro data:

{
  "id": "9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41",
  "content": "We just shipped scheduled threads.",
  "status": "scheduled"
}

As listas são paginadas (veja abaixo). Algumas respostas têm formato próprio, descrito na página delas: Listar tipos de conteúdo devolve { "platforms": [...] }, Listar etapas de ideias um array simples, Listar formatos de origem do repurpose { "data": [...] }, Criar posts em lote { "posts": [...] } e Criar chave de API { "token": {...}, "plain_token": "..." }.

Posts, notas, ideias, etapas de ideias, etiquetas, assinaturas e o workspace trazem as datas no formato Y-m-d H:i:s em UTC (2026-10-12 14:00:00). Chaves de API, webhooks, logs de webhook, reposts, uploads, horários livres da fila e o desempenho dos posts do canal usam ISO 8601. Nas análises, os principais posts usam Y-m-d H:i:s; as análises de publicação e a cobertura usam ISO 8601. Nas requisições, envie as datas em ISO 8601 com fuso ou Z (2026-10-12T14:00:00Z).

​

Paginação

Listas como posts, ideias, etiquetas, assinaturas, contas sociais, chaves de API, webhooks, logs de webhook, reposts e notas de posts são paginadas. Escolha a página com o parâmetro de consulta page:

curl "https://post.chatclean.com.br/api/posts?page=2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

O servidor define o tamanho da página; não existe parâmetro per_page. Leia o valor em meta.per_page em vez de supor um número (hoje é 25). A resposta usa o envelope padrão:

{
  "data": [
    { "id": "9d3c1f2a-6b4e-4c8a-9f1e-2a7b5c8d0e41", "...": "..." }
  ],
  "links": {
    "first": "https://post.chatclean.com.br/api/posts?page=1",
    "last": "https://post.chatclean.com.br/api/posts?page=3",
    "prev": "https://post.chatclean.com.br/api/posts?page=1",
    "next": "https://post.chatclean.com.br/api/posts?page=3"
  },
  "meta": {
    "current_page": 2,
    "from": 26,
    "last_page": 3,
    "path": "https://post.chatclean.com.br/api/posts",
    "per_page": 25,
    "to": 50,
    "total": 72,
    "links": [
      { "url": "https://post.chatclean.com.br/api/posts?page=1", "label": "« Previous", "page": 1, "active": false },
      { "url": "https://post.chatclean.com.br/api/posts?page=1", "label": "1", "page": 1, "active": false },
      { "url": "https://post.chatclean.com.br/api/posts?page=2", "label": "2", "page": 2, "active": true },
      { "url": "https://post.chatclean.com.br/api/posts?page=3", "label": "3", "page": 3, "active": false },
      { "url": "https://post.chatclean.com.br/api/posts?page=3", "label": "Next »", "page": 3, "active": false }
    ]
  }
}

Continue pedindo links.next até ele ser null.

​

Próximos passos

Publicação

Escolha um canal, preencha as configurações dele e agende, coloque na fila ou publique um post.

Envio de mídia

Envie arquivos, anexe a partir de URLs e reutilize mídia entre posts.