PATCH /v1/posts/:id

Aplique um patch parcial em um post que já existe. Só os campos que você envia mudam — tudo o que você omite fica exatamente como está.

• URL: https://api.canverly.com/v1/posts/{id}
• Método: PATCH
• Auth: chave de API Bearer — escopo posts:write
• Content-Type: application/json
• Limite de requisição: 60 req/min por chave

Uma chave só edita posts do próprio site: um id que pertence a outro site retorna 404, nunca 403.

Corpo da requisição

Campo	Tipo	Observações
title	string	Ignorado quando vazio ou só com espaços em branco.
blocks_json	object	Um documento de blocos completo. Ele substitui o corpo e passa pela mesma etapa de normalização + sanitização por allowlist da criação.
excerpt	string	Também gravado na description de SEO do post.
category_slugs	string[]	Substitui a lista de categorias.
tag_slugs	string[]	Substitui a lista de tags.
published_at	string	RFC-3339. Move ou retroage a data de publicação de um post no ar e dispara de novo o ping do IndexNow no upstream.

Um corpo sem nenhum desses campos — ou cujo único campo era um title vazio — é um 400 no updatable fields provided, não uma ida e volta silenciosa sem efeito.

O que o PATCH não faz

Não existe campo status nem slug nesta rota. Você não consegue passar um rascunho para publicado nem renomear a URL dele por ela. O estado de publicação é decidido no momento da criação, no admin ou — para tirar um post do ar — com POST /v1/posts/{reference}/unpublish, abaixo.

POST /v1/posts/{reference}/unpublish

Escopo: posts:write. Tira do ar um post publicado: ele passa para archived, o evento de despublicação é emitido e a página em cache é purgada — então o artigo deixa de poder ser lido na hora, não quando um TTL expira.

reference é o id do post ou o slug dele; adicione ?language= quando o mesmo slug existir em mais de um idioma.

curl -X POST https://api.canverly.com/v1/posts/como-fazer-x/unpublish   -H "Authorization: Bearer ck_live_xxx"

{ "id": "01J8ZQ7X4K2N5M9P0R3T6V8W1Y", "slug": "como-fazer-x", "status": "archived" }

Um post que não está publicado retorna 409 — um conflito de estado, não uma falha do servidor. Essa distinção não é cosmética: antes a resposta era 500 internal error, e a plataforma oculta o corpo das respostas 5xx, então a única frase que dizia o que fazer de diferente era apagada no caminho.

Despublicar não é excluir

O post sai do site e fica no arquivo — nada é destruído, e o admin pode publicá-lo de novo. Não existe endpoint de exclusão: remover conteúdo de vez é uma decisão sobre revisões, vínculos de taxonomia, sitemaps e mecanismos de busca, não um verbo em uma rota.

Se você automatiza a publicação, integre esta rota: um agente que consegue publicar e não consegue tirar do ar precisa de um humano com sessão no navegador para conter o próprio erro.

Exemplos

Corrigir um erro de digitação no título e atualizar o resumo:

curl -X PATCH https://api.canverly.com/v1/posts/01J8ZQ7X4K2N5M9P0R3T6V8W1Y \
  -H "Authorization: Bearer ck_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How to do X, properly",
    "excerpt": "A corrected one-sentence summary."
  }'

Substituir o corpo:

curl -X PATCH https://api.canverly.com/v1/posts/01J8ZQ7X4K2N5M9P0R3T6V8W1Y \
  -H "Authorization: Bearer ck_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "blocks_json": {
      "v": 1,
      "blocks": [
        { "id": "h1", "type": "heading", "attrs": { "level": 2 }, "text": "Rewritten" },
        { "id": "p1", "type": "paragraph", "text": "New body text." }
      ]
    }
  }'

Retroagir a data de um post — o caso de campanha para o qual esta rota existe:

curl -X PATCH https://api.canverly.com/v1/posts/01J8ZQ7X4K2N5M9P0R3T6V8W1Y \
  -H "Authorization: Bearer ck_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "published_at": "2026-05-14T09:00:00Z" }'

Dica

Envie published_at só quando a data estiver de fato errada. Reenviar a data que o post já tem ainda conta como edição e ainda dispara de novo o ping do IndexNow.

excerpt, category_slugs e tag_slugs ficam no bloco de SEO do post

Esses três campos são armazenados dentro do objeto de SEO do post. A API os mescla com o que já está lá, então um PATCH que leva só category_slugs não mexe em title, description, og_image, canonical_url, no_index, schema_type e tag_slugs do SEO do post.

Para qualquer coisa além desses três campos, use PATCH /v1/posts/{reference}/seo, que grava a allowlist inteira e mescla do mesmo jeito.

Trocar tags e categorias:

curl -X PATCH https://api.canverly.com/v1/posts/01J8ZQ7X4K2N5M9P0R3T6V8W1Y \
  -H "Authorization: Bearer ck_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "category_slugs": ["news", "opinion"], "tag_slugs": ["api"] }'

Resposta

200 OK

O registro do post atualizado, como o serviço de conteúdo o armazena. Esta é a representação interna, não o formato público enxuto retornado por GET /v1/posts/{reference}:

{
  "id": "01J8ZQ7X4K2N5M9P0R3T6V8W1Y",
  "site_id": "01KVPWYKT6AJDGG2EJN7DW4VT5",
  "org_id": "01KVPWYKT6AJDGG2EJN7DW4VT4",
  "type": "post",
  "post_type_slug": "post",
  "status": "published",
  "slug": "how-to-do-x",
  "title": "How to do X, properly",
  "excerpt": "A corrected one-sentence summary.",
  "blocks_json": { "v": 1, "blocks": [] },
  "seo_json": { "description": "A corrected one-sentence summary." },
  "fields": {},
  "author_id": "01KVPWYKT6AJDGG2EJN7DW4VT3",
  "persona_id": null,
  "featured_image_id": null,
  "published_at": "2026-05-14T09:00:00Z",
  "canonical_url": "",
  "access": "public",
  "language": "pt-BR",
  "is_primary_translation": true,
  "created_at": "2026-05-14T09:00:00Z",
  "updated_at": "2026-08-26T11:04:00Z"
}

Leia id, slug, status, published_at e updated_at dele; trate o resto como informativo. Campos novos podem aparecer aqui sem aviso.

Erros

Envelope: { "error": { "code", "message" } }. Tabela completa em Erros e limites de requisição.

Status	error.code	Quando
400	bad_request	Patch vazio (no updatable fields provided) ou JSON malformado.
401	unauthorized	Chave ausente/inválida/revogada.
403	forbidden	A chave não tem posts:write.
404	not_found	Não existe esse post neste site.
429	rate_limited	Acima de 60 req/min — respeite o Retry-After.
502	upstream	Transitório; tente de novo com backoff.

Veja também

• Criar um post — POST /v1/posts.
• SEO do post — título, descrição, canonical, no_index e companhia ficam em /v1/posts/{reference}/seo, não aqui.
• Importação em lote — para muitos posts de uma vez.