Referência da API

Tudo o que a API pública serve, em uma única tabela. A URL base é https://api.canverly.com para todas as rotas, e o site é sempre obtido da chave de API — não existe parâmetro de site em nenhum ponto desta superfície.

• Contrato para máquinas: /openapi.json (OpenAPI 3.1) · visualizador interativo
• Contrato para agentes: llms.txt
• Autenticação: Authorization: Bearer ck_…; as duas rotas de leitura também aceitam uma chave pública pk_… — veja Chaves, escopos e restrições

Conteúdo

Método	Caminho	Escopo	Página
GET	/v1/posts	posts:read	Listar posts
POST	/v1/posts	posts:write	Criar um post
GET	/v1/posts/{reference}	posts:read	Obter um post
PATCH	/v1/posts/{id}	posts:write	Atualizar um post
GET	/v1/post-types	post_types:read	Tipos de post

SEO

Método	Caminho	Escopo	Página
GET	/v1/posts/{reference}/seo	seo:read	SEO do post
PATCH	/v1/posts/{reference}/seo	seo:write	SEO do post
GET	/v1/sites/me/seo	seo:read	SEO do site
PATCH	/v1/sites/me/seo	seo:write	SEO do site

Mídia

Método	Caminho	Escopo	Página
GET	/v1/media	media:read	Mídia
POST	/v1/media	media:write	Mídia
GET	/v1/media/{id}	media:read	Mídia
DELETE	/v1/media/{id}	media:write	Mídia

Site

Método	Caminho	Escopo	Página
GET	/v1/sites/me	sites:read	Informações do site
GET	/v1/sites/me/settings	site:read	Configurações do site
PATCH	/v1/sites/me/settings	site:write	Configurações do site

Nota

sites:read (a chamada de identidade GET /v1/sites/me) e site:read / site:write (o blob de configurações) são escopos diferentes, e o singular/plural não é um erro de digitação. Uma chave que consegue ler o domínio do site não consegue necessariamente ler as configurações dele.

Audiência e dados

Método	Caminho	Escopo	Página
GET	/v1/analytics/summary	analytics:read	Analytics
GET	/v1/analytics/posts	analytics:read	Analytics
GET	/v1/leads	leads:read	Leads
GET	/v1/leads/{id}	leads:read	Leads
GET	/v1/export	export (+ leads:read / analytics:read)	Exportação e importação em massa
POST	/v1/import	import + posts:write	Exportação e importação em massa

Gerenciamento de chaves

POST, GET /admin/api-keys e PATCH, DELETE /admin/api-keys/{id} também existem, mas não fazem parte da superfície do integrador: eles autenticam com uma sessão de navegador do dono do site, não com uma chave ck_. Veja Chaves, escopos e restrições.

Convenções que valem em todo lugar

• A chave fixa o site. site_id, org_id e author_id nunca são lidos de URL, query ou corpo. Enviá-los não muda nada.
• 404, não 403, para outros tenants. Um recurso que pertence a outro site é indistinguível de um que não existe. Isso é proposital: um 403 confirmaria que o rascunho, o lead ou o asset de outra pessoa existe.
• Limites nunca são ajustados em silêncio. Um limit fora do intervalo documentado é um 400 com o intervalo na mensagem, não uma página truncada sem aviso.
• Um único envelope de erro: { "error": { "code": …, "message": … } }. Veja Erros e limites de requisição.