Metadados de SEO

Quatro rotas, dois níveis: por post (título, descrição, canonical, indexação, tipo de schema) e do site inteiro (os padrões e templates que toda página herda).

Método	Caminho	Escopo
GET	/v1/posts/{reference}/seo	seo:read
PATCH	/v1/posts/{reference}/seo	seo:write
GET	/v1/sites/me/seo	seo:read
PATCH	/v1/sites/me/seo	seo:write

Leitura e escrita são escopos separados: uma chave que lê SEO não consegue gravá-lo. Limite de requisição: 60 req/min por chave.

Formato do corpo

As duas rotas PATCH aceitam qualquer uma das formas — o wrapper é opcional:

{ "seo": { "title": "…", "description": "…" } }

{ "title": "…", "description": "…" }

As duas rotas GET sempre respondem na forma com wrapper, { "seo": { … } }, e com um objeto vazio quando nada foi definido ainda. Chaves fora da allowlist daquele nível são descartadas em silêncio; um corpo sem nenhuma chave da allowlist é um 400 cuja mensagem lista as chaves aceitas.

GET /v1/posts/{reference}/seo

curl -s https://api.canverly.com/v1/posts/01J8ZQ7X4K2N5M9P0R3T6V8W1Y/seo \
  -H "Authorization: Bearer ck_live_xxx"

{
  "seo": {
    "title": "How to do X — a practical guide",
    "description": "Step by step, with the pitfalls.",
    "og_image": "https://cdn.example.com/x-og.png",
    "twitter_card": "summary_large_image",
    "no_index": false,
    "canonical_url": "https://blog.example.com/how-to-do-x",
    "schema_type": "BlogPosting",
    "category_slugs": ["guides"],
    "tag_slugs": ["x"]
  }
}

Id ou slug

reference é o id do post (ULID) ou o slug dele, resolvido exatamente como em GET /v1/posts/{reference} — inclusive posts que ainda não estão no ar. Adicione ?language= quando o mesmo slug existir em mais de um idioma. Um post que pertence a outro site retorna 404.

Esta rota antes aceitava só o id, o que significava que você podia ler um post pelo slug e depois precisava ter um id em mãos para gravar o SEO dele. Se você mantinha um mapa slug→id por esse motivo, não precisa mais dele.

PATCH /v1/posts/{reference}/seo

Chaves da allowlist:

Chave	Tipo	Observações
title	string	Título meta/OG deste post.
description	string	Meta description.
og_image	string (URI)	Imagem Open Graph.
twitter_card	string	Ex.: summary_large_image.
no_index	boolean	true mantém o post fora dos índices de busca.
canonical_url	string (URI)	Sobrescreve o link canonical.
schema_type	string	Article, BlogPosting ou NewsArticle.
category_slugs	string[]	Alimenta os arquivos de categoria.
tag_slugs	string[]	Alimenta os arquivos de tag.

Isto é um merge — as chaves que você omite sobrevivem

A API lê o bloco de SEO atual do post e sobrepõe as chaves que você envia. Um PATCH de { "no_index": true } deixa title, description, category_slugs e todo o resto exatamente como estavam.

Para limpar um campo, envie-o explicitamente com valor vazio — "description": "" ou "category_slugs": []. Omitir um campo significa “deixe como está”, nunca “apague”.

O SEO do site (abaixo) se comporta do mesmo jeito. Se a API não consegue ler o SEO atual do post — porque o serviço de conteúdo está momentaneamente inacessível — o PATCH falha em vez de gravar um objeto parcial por cima de um completo.

# 1. leia o que está lá
curl -s https://api.canverly.com/v1/posts/01J8ZQ7X4K2N5M9P0R3T6V8W1Y/seo \
  -H "Authorization: Bearer ck_live_xxx"

# 2. envie o objeto COMPLETO de volta, com a sua alteração aplicada
curl -X PATCH https://api.canverly.com/v1/posts/01J8ZQ7X4K2N5M9P0R3T6V8W1Y/seo \
  -H "Authorization: Bearer ck_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "seo": {
      "title": "How to do X — a practical guide",
      "description": "Step by step, with the pitfalls.",
      "schema_type": "BlogPosting",
      "category_slugs": ["guides"],
      "tag_slugs": ["x"],
      "no_index": true
    }
  }'

200 OK retorna o objeto armazenado no mesmo formato com wrapper.

Dica

schema_type: "NewsArticle" faz mais do que mudar o @type do JSON-LD: é também o que inclui o post no sitemap do Google News do site.

GET /v1/sites/me/seo

Os padrões do site inteiro, armazenados nas configurações do site.

curl -s https://api.canverly.com/v1/sites/me/seo \
  -H "Authorization: Bearer ck_live_xxx"

{
  "seo": {
    "title_template": "%s — Example Blog",
    "default_title": "Example Blog",
    "default_description": "Notes on doing X well.",
    "default_og_image": "https://cdn.example.com/og-default.png",
    "twitter_card": "summary_large_image",
    "twitter_handle": "@exampleblog",
    "robots": "index,follow"
  }
}

PATCH /v1/sites/me/seo

Chaves da allowlist: title_template, default_title, default_description, default_og_image, twitter_card, twitter_handle, robots.

Esta é mesclada com o SEO do site armazenado — as chaves que você omite mantêm o valor atual, e o resto do blob de configurações do site não é tocado.

curl -X PATCH https://api.canverly.com/v1/sites/me/seo \
  -H "Authorization: Bearer ck_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "default_description": "Notes on doing X well.", "robots": "index,follow" }'

200 OK retorna o objeto mesclado, com wrapper, como { "seo": { … } }.

Erros

Status	error.code	Quando
400	bad_request	O corpo não é um objeto JSON ou não traz nenhuma chave da allowlist (no updatable SEO fields provided (allowed: …)).
401	unauthorized	Chave ausente/inválida/revogada.
403	forbidden	A chave não tem seo:read / seo:write.
404	not_found	Rotas de post: não existe esse post neste site (ou foi passado um slug em vez de um id).
429	rate_limited	Acima de 60 req/min — respeite o Retry-After.

Veja também

• Configurações do site — tudo sobre o site que não é SEO. seo fica de fora daquela rota de propósito; ele mora aqui.
• Atualizar um post — note que enviar category_slugs, tag_slugs ou excerpt lá grava no mesmo bloco de SEO.