Autenticación

Toda llamada salvo GET /v1/health y POST /v1/validate/* lleva una clave de API.

La cabecera

Envía Authorization: Bearer <key>. Las claves se crean en el panel. La clave completa se muestra una vez: solo se guarda su hash SHA-256, así que una clave perdida no se puede recuperar; crea una nueva y revoca la antigua.

Authorization: Bearer co_live_…

Tres tipos de clave

Claves live: para producción. Van con un plan de la Engine API y consumen su cuota mensual.
Claves de prueba: gratis para cualquier cuenta con sesión iniciada; 1000 llamadas al mes, nunca facturadas, contadas aparte de las claves live. GET /v1/usage responde env: "test" para ellas.
La clave de demostración pública: detrás de los botones «Run this example»; sin cuenta, solo trabajos síncronos pequeños de 2D, 1D y madera, con límite de frecuencia. Cada respuesta lleva X-CutOptim-Demo: true.

Una cuota por cuenta

Una cuenta tiene hasta 10 claves live activas, y todas consumen la misma cuota mensual: más claves no dan más llamadas. Sirven para separar entornos e integraciones. Cuando la cuota se agota, todas las claves responden 402 hasta que cambia el mes o se elige un plan mayor.

Rotar y revocar una clave

Crea la clave nueva, cambia tu integración a ella y luego revoca la antigua en el panel. Una clave revocada se rechaza al instante con 403 key_revoked. Revocar no es una operación de facturación y no devuelve las llamadas ya gastadas.

GET /v1/usage

{
  "plan": "studio",
  "used": 137,
  "limit": 10000,
  "remaining": 9863,
  "periodEnd": "2026-08-01",
  "keyPrefix": "co_live_ab12",
  "contractVersion": "1"
}

Solo lectura: no consume una llamada y no envía cabeceras de límite de tasa.

⚠️ used y limit describen la CUENTA, no la clave con la que llamaste: cada clave activa de la cuenta consume de una única asignación compartida, así que crear más claves no crea más cuota. used cuenta el mes natural UTC en curso a través de todas ellas, remaining es limit menos used y nunca es negativo, periodEnd es el día de reinicio como una simple fecha YYYY-MM-DD, y keyPrefix es el prefijo de visualización no secreto de la clave con la que llamaste.

La clave en sí nunca la devuelve ningún endpoint — solo se almacena su hash, así que una clave perdida se sustituye, no se recupera.

Campo	Tipo	Descripción
plan	string	The tier slug frozen onto the key when it was minted. Re-pricing the product later does not rewrite a live key.
used	integer	Calls counted in the current UTC calendar month, across EVERY key on the account — revoked keys included, so revoking a key cannot un-spend what it spent (053) — not just the one you called with. The quota is account-wide.
limit	integer	The monthly cap for the ACCOUNT: the largest monthly quota frozen onto any of its ACTIVE keys (049). All active keys draw on this one allowance; creating more keys does not create more quota. Keys are for separating environments and integrations (and for revoking one without disturbing the rest).
remaining	integer	`limit` − `used`, never negative.
periodEnd	string (date)	First day of next month as `YYYY-MM-DD` — a DATE, not a timestamp. The counter resets at 00:00 UTC on that day.
keyPrefix	string	Non-secret display prefix of the calling key, so you can tell which key you queried. The key itself is never returned by any endpoint.
contractVersion	string	Shape version. Currently `"1"`.
env	"test"	Present (`"test"`) only for a TEST key: created in the dashboard, never billed, with its own monthly allowance separate from the live keys. Absent for a live key — a live key gets exactly the body it always got.
keyClass	"tenant"	Present (`"tenant"`) only for a key CutOptim issues to its own first-party service. Absent for every key you create in the dashboard.