Versões da API

A sua integração não quebra quando o Cord muda: cada chave e cada endpoint de webhook ficam na versão com que foram criados.

Versão vigente

A versão vigente é 2026-10-01. Ela também é a única: a versão base que fixou o formato da API quando o Cord começou a versioná-la. Cada versão recebe o nome da data em que é publicada.

Versão	Alterações
`2026-10-01`	Versão base: o formato da API quando o versionamento foi fixado.

Como a versão de uma requisição é escolhida

O Cord resolve a versão de cada requisição a /api/v1 nesta ordem:

O header Cord-Version da requisição, se você o enviar.
A versão fixada da chave. Cada chave fica fixada na versão vigente no dia em que é criada. Rotacionar uma chave mantém a versão da anterior.
A versão base (2026-10-01), para chaves criadas antes de o versionamento existir.

O Cord produz cada resposta no seu formato mais recente e a converte, alteração por alteração, para a versão resolvida. Toda resposta traz o header Cord-Version com a versão em que foi respondida.

curl -i https://cordhq.app/api/v1/me \
  -H "Authorization: Bearer sk_test_..." \
  -H "Cord-Version: 2026-10-01"

HTTP/2 200
content-type: application/json
cord-request-id: req_3f9c2a1b7d4e6f8a0b1c2d3e
cord-version: 2026-10-01

Hoje não há como alterar a versão fixada de uma chave existente. Para passar para uma versão nova, envie o header Cord-Version nas suas requisições ou crie uma chave nova.

Nos SDKs e na CLI

Os clientes oficiais sempre enviam a versão com que foram construídos, então atualizar o Cord não muda o que eles leem:

Cliente	Versão que envia	Como alterá-la
`@flouviahq/node`	`CORD_API_VERSION` (`2026-10-01`)	`new Cord(sk, { apiVersion: '2026-10-01' })`
`@flouviahq/elements`	`CORD_API_VERSION` (`2026-10-01`)	É atualizada com o pacote.
`@flouviahq/cli`	`2026-10-01`	É atualizada com o pacote.

import { Cord, CORD_API_VERSION } from '@flouviahq/node';

const cord = new Cord(process.env.CORD_SECRET_KEY!, { apiVersion: CORD_API_VERSION });

Webhooks

Cada endpoint de webhook fica fixado na versão vigente no dia em que é criado, seja pelo Workbench, por POST /api/v1/webhooks ou com uma sessão de cord listen. O data de cada entrega é convertido para a versão desse endpoint, não para a da chave que provocou o evento. Se você tiver dois endpoints em versões diferentes, os dois recebem o mesmo evento, com o mesmo id, cada um no seu formato.

As entregas não trazem o header Cord-Version, e não há um header para pedir outra versão por entrega: para receber outro formato, crie um endpoint novo.

Versão inválida

Uma versão que não existe responde 400 com code: "invalid_api_version". O Cord nunca passa em silêncio para outra versão. A mensagem lista as versões disponíveis:

curl https://cordhq.app/api/v1/me \
  -H "Authorization: Bearer sk_test_..." \
  -H "Cord-Version: 2025-01-01"

{
  "error": "Cord-Version \"2025-01-01\" no existe. Versiones disponibles: 2026-10-01.",
  "code": "invalid_api_version",
  "request_id": "req_8a1c4e7b2d9f3a6c0e5b8d1f",
  "doc_url": "https://docs.cordhq.app/docs/desarrolladores/esenciales/errores#invalid_api_version"
}

O formato também importa: Cord-Version: 2026-10 ou latest respondem com o mesmo erro.

Política de alterações

Exige uma versão nova (nunca chega à sua integração sem que você a peça):

remover ou renomear um campo de uma resposta ou de um webhook;
alterar o tipo ou o significado de um campo;
alterar um código de erro.

Chega sem versão nova, porque não quebra uma integração bem escrita:

campos novos em uma resposta ou no data de um webhook;
tipos de evento novos;
endpoints novos e parâmetros opcionais novos.

O texto do campo error é uma mensagem para pessoas e pode melhorar a qualquer momento: programe com base em code, nunca no texto.

A sua integração deve ignorar os campos que não conhece e tratar um tipo de evento desconhecido como algo que pode descartar. Se você deixou os eventos de um endpoint sem marcar, recebe todos, incluindo os que o Cord adicionar depois.

Quando houver uma versão nova, ela aparecerá na tabela acima com o que mudou.