Automação

O Chinaski expõe uma API REST em JSON para que scripts, cron jobs e assistentes de IA leiam seu conteúdo, o criem e o atualizem, despachem builds e executem jobs em lote: tudo o que você normalmente clicaria na área de admin, menos a exclusão. Esta página é a orientação para automatizar contra ela; a referência endpoint por endpoint fica em outra parte da seção Reference, e a superfície de assistente de IA tem sua própria página MCP.

Autenticação

O acesso automatizado usa chaves de API, criadas por um admin em Settings → API Keys. Cada chave é nomeada, tem sua própria data de expiração (opcional) e tem escopo de leitura ou escrita:

Chaves de leitura podem buscar, mas nunca modificam conteúdo.
Chaves de escrita podem criar e atualizar; isso é explicitamente exigido para qualquer chamada POST/PUT, independentemente do que o handler faria.
As requisições se identificam com um header X-API-Key. Chaves ausentes ou expiradas recebem um 401; uma chave de leitura tentando escrever recebe um 403.

O acesso de API pode ser desligado inteiramente pela aba API Keys do admin: com ele desligado, cada requisição de API responde 503 "API access is disabled".

O rate limiting é por chave, a cada 60 segundos, com padrão de 100 requisições por minuto (configurável em Settings). Excedê-lo retorna um 429 com um header Retry-After dizendo quanto esperar.

Cada uso de chave é registrado na trilha de auditoria com o método e o caminho HTTP, e o timestamp de último uso é rastreado por chave, o que ajuda a encontrar chaves que deveriam ser aposentadas.

O que a API pode fazer

Leitura: páginas publicadas, posts, blocos, snippets, categorias, documentos, navegação, redirecionamentos, autores, campos personalizados, cobertura de tradução e workflows, busca por palavra-chave, relatórios de lacunas de conteúdo e todas as configurações não secretas. As listas são paginadas (data mais um bloco meta com total/page/limit/pages) e enxugadas a menos que você peça as linhas completas.
Criação e atualização: POST/PUT para páginas, posts, blocos, snippets, categorias, documentos, autores e itens de navegação, incluindo variantes upsert que criam-ou-atualizam por slug e idioma, mais configuração de webhooks e gravações de configurações. Valores secretos de configurações são criptografados na entrada, chaves desconhecidas são rejeitadas por item, e os valores de URL de webhook são validados por segurança.
Build: POST de um disparo para reconstruir o site estático (a resposta reporta dispatched / already-busy / missing), depois GET do status de build para progresso por idioma: páginas e posts concluídos vs. total, item atual e mensagem de erro.
A exclusão não faz parte da API: não há endpoints DELETE; a exclusão permanente ou para a lixeira acontece na UI de admin. Scripts que precisam aposentar conteúdo devem publicar/marcar em vez de apagar, ou fazer a exclusão à mão.

Jobs em lote

Para trabalho pesado, envie um job assíncrono em vez de muitas chamadas únicas:

Enviar: POST /api/jobs com um tipo (bulk_upsert_pages, bulk_upsert_posts ou bulk_create_blocks) e um array items não vazio.
Consultar: GET /api/jobs/:id retorna o status do job, o progresso (total e concluído) e o payload de resultado uma vez terminado.

Monitoramento: um status no estilo GET /build/status também é exposto; e GET /api/health é o endpoint de saúde não autenticado que seu monitor de uptime pode acessar: ele reporta status, a contagem de páginas publicadas, a hora do último build e se um build está em andamento, e levanta um aviso se houve páginas publicadas mas nunca um build.

Fluxos de trabalho assistidos por IA

O servidor MCP embutido é o portal pretendido para assistentes de IA como o Claude Code: ele é lançado localmente como um processo JSON-RPC-over-stdio, conversa com esta mesma API REST usando uma chave de API, e expõe ferramentas de nível mais alto por cima: criação de página/post em uma chamada com blocos, tradução de conteúdo com auditoria automática de lacunas, bulk import/upsert, limpeza de blocos órfãos e auditorias de qualidade de conteúdo. Aponte-o para a URL do seu CMS e uma chave de API com capacidade de escrita, e seu assistente trabalha diretamente contra a API.

Bons hábitos para scripts

Dê aos scripts suas próprias chaves de API nomeadas para que as entradas de auditoria os identifiquem distintamente, e defina uma expiração em chaves temporárias. O uso da chave atualiza last_used_at de forma auditada; limpe as não usadas na aba API Keys.
Leve a divisão leitura/escrita a sério: uma chave que só lê não deveria guardar permissão de escrita "por precaução".
Cuidado com os segredos: configurações buscadas pela API nunca incluem valores secretos (a senha SMTP e os segredos de webhook são sempre omitidos), e o caminho de escrita criptografa novos valores secretos adequadamente.