API

A API e o MCP usam as mesmas regras das telas: contas do seu espaço, formatos de mídia, permissões e proteção contra envio duplicado.

Conectar uma integração

Em Integrações, crie uma chave com as permissões necessárias. O segredo aparece uma vez; copie para a configuração privada do seu cliente. Envie Authorization: Bearer <SUA_CHAVE> nas rotas /v1 ou no endpoint MCP /mcp. Chaves antigas mantêm seus escopos; para liberar Feed ou Caixa, crie uma chave com essas permissões.

Para conectar uma conta social, abra a URL retornada estando conectado ao Piloto como o dono da chave. O consentimento da rede continua sendo feito no navegador.

O contrato OpenAPI descreve parâmetros, corpos e escopos. A tela Integrações mostra o catálogo de operações REST e os nomes equivalentes no MCP. As ferramentas são expostas conforme a chave: uma chave somente de leitura não oferece ferramentas de envio.

As rotas /api abaixo usam a sessão do portal. Para integrar com chave, use as equivalentes em /v1; senha, 2FA, equipe, plano e gestão das chaves ficam no portal.

Agendar

PUT  /api/midia            → { id, tipo, url }
POST /api/publicacoes      → { id, agendado_para, contas, automacao, avisos }
GET  /api/publicacoes
PATCH  /api/publicacoes/:id   (só enquanto nada saiu)
DELETE /api/publicacoes/:id   (cancela o que não saiu)

A listagem aceita conta (ID da conta), de (inclusivo) e ate (exclusivo), com horários em milissegundos Unix. Para paginar, envie o valor opaco de proximo como antes, preservando os mesmos filtros. Não transforme esse cursor em número: ele distingue publicações que têm o mesmo horário.

A resposta inclui publicacoes, proximo, calendario e totais. O calendário resume todos os posts do período e da conta selecionados, mesmo quando a lista precisa de várias páginas. Os totais de agendados e publicados nos últimos 7 dias são globais da organização. Os mesmos filtros funcionam em GET /v1/publicacoes com chave de API.

O corpo de POST /api/publicacoes:

{
  "legenda": "comenta QUERO que eu mando o link",
  "midia": ["<id do PUT>"],
  "contas": ["<id da conta>"],
  "quando": "2026-08-13T18:00",
  "config": { "tiktok": { "legenda": "outra legenda aqui" } },
  "automacao": {
    "contaId": "<id da conta>",
    "keyword": "quero",
    "mensagem": "toma o link: ...",
    "exigirFollow": true
  }
}

quando em horário de Brasília quando não tiver fuso. Omitir coloca o post na fila para publicar agora; data ilegível devolve 400. O POST REST exige Idempotency-Key com 8 a 128 caracteres. No MCP, passe idempotencia em agendar_post. Use o mesmo valor e corpo ao retentar; um corpo diferente com a mesma chave devolve 409. Incluir automacao no agendamento exige também o escopo automacoes:escrever.

O upload recebe os bytes originais em PUT /v1/midia, com Content-Type e Content-Length. Pelo MCP, consulte instrucoes_upload_midia para enviar com seu cliente HTTP ou listar_midias para reutilizar um arquivo. Arquivos não vão em JSON/base64.

Feed e analytics

GET /v1/feed?conta=<id> lê os posts já sincronizados. Para buscar os posts reais da conta, inclusive os publicados fora do Piloto, use POST /v1/feed/sincronizar com { "conta": "<id>" }. O MCP oferece listar_feed e sincronizar_feed.

Cada sincronização importa até 20 posts. Para continuar na rede, devolva sincronizacao.paginaProxima em cursor no POST. Para paginar os posts já guardados, devolva proximo em antes no GET. Esses cursores têm funções diferentes. O cache é preservado em caso de falha e expira em 30 dias. Permissões e limitações ficam em contas; uma rede bloqueada não aparece como um feed vazio.

GET /v1/analytics aceita dias, conta, rede e origem: todos, piloto ou feed (posts feitos fora do Piloto). O relatório combina as publicações locais e o feed importado sem duplicar o mesmo post.

POST /v1/analytics atualiza até 30 posts do filtro. Se houver atualizacao.proximo, passe esse valor em cursor no próximo POST. forcar=1 reinicia a atualização ignorando o cache de uma hora; não o envie ao continuar um lote. O MCP oferece analytics_posts e atualizar_analytics com os mesmos filtros.

As métricas são acumuladas por post, agrupadas pela data de publicação; não representam interações ocorridas em cada dia. O relatório mostra quais métricas estão disponíveis e quando foram coletadas. YouTube é exibido separadamente por canal. O feed cobre o que já foi sincronizado e o que a API da rede permite ler, não todo o histórico automaticamente.

Contas, automações e caixa

GET    /api/contas
POST   /api/conectar/:plataforma      → { url } pra mandar o usuário
POST   /api/contas/:id/assinar        (retenta o webhook)
DELETE /api/contas/:id

GET    /api/automacoes
POST   /api/automacoes
PATCH  /api/automacoes/:id
DELETE /api/automacoes/:id

GET  /api/caixa
GET  /api/caixa/:id
POST /api/caixa/:id/lida
POST /api/caixa/:id/responder         → { texto, modo }

Responder exige Idempotency-Key também na Caixa. No MCP, use responder_conversa com idempotencia estável. A integração respeita a janela de resposta e informa resultados incertos; uma tentativa ambígua não é reenviada automaticamente.

Erros

Erro de validação volta em 422 com { erro, detalhes: [...] }, uma linha por problema e com a plataforma na frente — tiktok: aceita 1 vídeo, veio 0. Coisa que passa mas merece atenção volta em avisos, e não impede o agendamento.