Perguntas frequentes

Apenas os endpoints sob o prefixo /public, em cinco domínios: Posts, Categorias, Tags, Busca e Anúncios (Delivery). São rotas de leitura de conteúdo destinadas ao consumo por sites e aplicações de terceiros, autenticadas por chave de API. Outras funcionalidades da plataforma não fazem parte desta API e não são documentadas aqui.

A chave é gerada e gerenciada no painel do DraftIn, nas configurações do blog. Cada chave pertence a um blog e dá acesso somente ao conteúdo publicado daquele blog. Lá também é possível rotacioná-la. Veja Autenticação.

Não é recomendado. A chave identifica seu blog e deve ficar no servidor — em builds estáticos, rotas de API ou funções serverless. Expor a chave em JavaScript de cliente a torna visível para qualquer visitante.

Não. A API pública é somente leitura. A criação, edição e publicação de conteúdo acontecem no editor e no painel da DraftIn. Os únicos endpoints públicos que aceitam POST são os de anúncios (entrega em lote e tracking de clique), que não escrevem conteúdo editorial.

Os endpoints públicos só enxergam conteúdo com status PUBLISHED. Um post em rascunho ou agendado é, para esta API, equivalente a inexistente — e responde 404. Confirme que o post está publicado.

Use https://api.draftin.io em produção e http://localhost:3000 em desenvolvimento. Em caso de dúvida, confirme com o painel/equipe do DraftIn. Veja Base URL.

Todos os endpoints de conteúdo usam o envelope padrão { success, data, meta? }: o payload fica sempre em data e os metadados (como paginação) em meta. Isso permite evoluir a API sem quebrar integrações. A exceção são os endpoints de anúncios, que atendem um contrato legado sem envelope. Veja Formato das respostas.

Todos os endpoints retornam os itens em data, dentro do envelope padrão. O que varia são os parâmetros e os metadados: a listagem geral de posts usa limit/offset sem contagem total; as listagens por categoria e por tag usam page/pageSize com meta.pagination canônico; e a busca usa limit/offset com count próprio. A tabela em Paginação resume os três estilos.

Sim, mas as cotas numéricas não são publicadas. Ao exceder o limite, a API responde 429 com error.code: RATE_LIMIT_EXCEEDED e o header Retry-After indicando quantos segundos esperar. Cacheie respostas, faça chamadas no servidor e respeite o Retry-After — veja Rate limits.

A plataforma oferece webhooks de saída por blog, que notificam mudanças de estado de posts (criar, editar, publicar, excluir, restaurar) para que sites SSR façam redeploy/revalidação. Esses webhooks são configurados no painel — a administração deles não faz parte desta API pública, por isso não documentamos esses endpoints aqui. No seu site, você implementa um receptor que invalida o cache ao receber a notificação.

É uma API REST sobre HTTPS, com respostas JSON. Não há interface GraphQL ou outra forma de consulta documentada.

O campo content pode conter HTML ou Markdown, conforme produzido no editor. Ao renderizar HTML de fontes não totalmente confiáveis, sanitize antes de injetar no DOM.

A impressão é registrada automaticamente no servidor no momento da entrega — você não precisa chamar nenhum endpoint para isso. O clique é registrado por você chamando POST /public/ads/tracking/click com o clickToken recebido na entrega, que tem proteções anti-fraude (uso único, TTL de 10 min, validação de origem e deduplicação por IP). Veja Anúncios · Delivery.

Não há um SDK oficial. Como a API é REST simples, um cliente próprio de poucas linhas costuma bastar — há um exemplo em Autenticação e tipos prontos em Modelos de dados.