Saltar al contenido
ESEN

Versiones de la API

Tu integración no se rompe cuando Cord cambia: cada llave y cada endpoint de webhook se quedan en la versión con la que nacieron.

Versión vigente

La versión vigente es 2026-10-01. Es también la única: la versión base que fijó la forma de la API cuando Cord empezó a versionarla. Cada versión se nombra con la fecha en que se publica.

Versión Cambios
2026-10-01 Versión base: la forma de la API cuando se fijó el versionado.

Cómo se elige la versión de una petición

Cord resuelve la versión de cada petición a /api/v1 en este orden:

  1. El header Cord-Version de la petición, si lo mandas.
  2. La versión fijada de la llave. Cada llave queda fijada a la versión vigente el día que se crea. Rotar una llave conserva la versión de la anterior.
  3. La versión base (2026-10-01), para llaves creadas antes de que existiera el versionado.

Cord produce cada respuesta en su forma más nueva y la convierte, cambio por cambio, a la versión resuelta. Toda respuesta trae el header Cord-Version con la versión con la que se respondió.

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

Hoy no hay forma de cambiar la versión fijada de una llave existente. Para moverte a una versión nueva, manda el header Cord-Version en tus peticiones o crea una llave nueva.

En los SDK y el CLI

Los clientes oficiales mandan siempre la versión con la que se construyeron, así que actualizar Cord no cambia lo que leen:

Cliente Versión que manda Cómo cambiarla
@flouviahq/node CORD_API_VERSION (2026-10-01) new Cord(sk, { apiVersion: '2026-10-01' })
@flouviahq/elements CORD_API_VERSION (2026-10-01) Se actualiza con el paquete.
@flouviahq/cli 2026-10-01 Se actualiza con el paquete. 
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 queda fijado a la versión vigente el día que se crea, ya sea desde el Workbench, por POST /api/v1/webhooks o con una sesión de cord listen. El data de cada entrega se convierte a la versión de ese endpoint, no a la de la llave que provocó el evento. Si tienes dos endpoints en versiones distintas, ambos reciben el mismo evento, con el mismo id, cada uno en su forma.

Las entregas no llevan el header Cord-Version, y no hay un header para pedir otra versión por entrega: para recibir otra forma, crea un endpoint nuevo.

Versión inválida

Una versión que no existe responde 400 con code: "invalid_api_version". Cord nunca cae en silencio a otra versión. El mensaje lista las versiones disponibles:

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"
}

El formato también importa: Cord-Version: 2026-10 o latest responden el mismo error.

Política de cambios

Requiere una versión nueva (nunca llega a tu integración sin que la pidas):

  • quitar o renombrar un campo de una respuesta o de un webhook;
  • cambiar el tipo o el significado de un campo;
  • cambiar un código de error.

Llega sin versión nueva, porque no rompe una integración bien escrita:

  • campos nuevos en una respuesta o en el data de un webhook;
  • tipos de evento nuevos;
  • endpoints nuevos y parámetros opcionales nuevos.

El texto del campo error es un mensaje para personas y puede mejorar en cualquier momento: programa contra code, nunca contra el texto.

Tu integración debe ignorar los campos que no conoce y tratar un tipo de evento desconocido como algo que puede descartar. Si dejaste los eventos de un endpoint sin marcar, recibes todos, incluidos los que Cord agregue después.

Cuando exista una versión nueva, aparecerá en la tabla de arriba con lo que cambió.