Read-only by design

Todo lo que un integrador necesita para usar la Developer API de CtrlZ.

Esta guia conecta la capa comercial con la tecnica: que resuelve, como se autentica, que endpoints usar primero, limites de v1 y como pasar de descubrimiento de schema a consultas SQL seguras.

Para que sirve

Explorar schema, entender relaciones y ejecutar consultas `SELECT` sobre la conexion activa del tenant.

Auth

Tokens de servicio creados por un admin en `Security -> Developer access`. Cada token representa un tenant.

Limites v1

Sin writes, sin chat NL, sin voz, sin OAuth de usuario. Solo lectura y foco REST-first.

Quickstart

Como se integra en v1

La experiencia esta pensada para cualquier equipo tecnico que quiera conectarse rapido sin tocar credenciales de base de datos ni implementar un SDK propio.

Crear token

Un admin Pro entra al dashboard y crea un service token desde `Security -> Developer access`.

Descubrir schema

El integrador usa endpoints de metadata para entender tablas, columnas, relaciones y fechas relevantes.

Consultar

Las consultas pasan por validacion read-only, chequeo de plan y `LIMIT` automatico cuando hace falta.

Operar con trazabilidad

Cada request autenticada actualiza `last_used_at` y las queries mantienen la auditoria ya existente de CtrlZ.

Que incluye

check_circleREST API publica estable para schema, tablas, relaciones y `SELECT` read-only.
check_circleTokens tenant-scoped, sin exponer `connection_id` ni credenciales de base de datos.
check_circleCompatibilidad MCP para clientes y agentes que prefieran ese protocolo.
check_circleSwagger y ReDoc para inspeccionar schemas y probar requests desde el navegador.

Que no incluye en v1

blockNo se permiten `INSERT`, `UPDATE`, `DELETE`, `DROP` ni otra mutacion SQL.
blockNo hay chat de lenguaje natural completo ni herramientas de voz en esta superficie.
blockNo hay OAuth de usuario final; el token representa al tenant completo.
blockSolo tenants Pro pueden crear y usar estos tokens.

Reference

Catalogo de endpoints v1

Los endpoints de metadata no consumen cuota de consultas. Solo `POST /query` mantiene la semantica normal de uso y guardrails.

Metodo

Ruta

Uso principal

GET

/health

Chequeo simple del canal Developer API.

GET

/schema

Lista tablas y columnas visibles en la conexion activa del tenant.

GET

/schema/search?q=...

Busca tablas y columnas por concepto de negocio.

GET

/tables/{table_name}

Devuelve metadata detallada de una tabla especifica.

GET

/tables/{table_name}/relationships

Expone relaciones detectadas para navegar joins y dependencias.

GET

/tables/{table_name}/date-range?column=...

Encuentra min/max en columnas de fecha para orientar filtros temporales.

GET

/tables/{table_name}/distinct-values?column=...&limit=20

Devuelve valores distintos utiles para filtros y enumeraciones.

POST

/query

Ejecuta `SELECT` con validacion read-only, `LIMIT` automatico y auditoria.

Errores consistentes

Todas las respuestas no-2xx usan la misma forma para que el integrador pueda manejar errores sin parseos especiales.

{
  "error": {
    "code": "readonly_violation",
    "message": "Only read-only SELECT queries are allowed."
  }
}

Casos operativos comunes

401 / missing_token: falta `Authorization: Bearer ...`.
403 / plan_upgrade_required: el tenant no esta en plan Pro.
404 / table_not_found: la tabla o columna no existe para la conexion activa.
400 / readonly_violation: la SQL intenta escribir, alterar o borrar datos.
409 o 422: parametros invalidos o tenant sin conexion activa.

Examples

Ejemplos listos para copiar

Puedes empezar con estos snippets y luego pasar a Swagger o ReDoc para inspeccionar payloads completos.

curl

bash

TOKEN="cz_mcp_..."
BASE="https://app.ctrlz.app/api/developer/v1"

curl -sS \
  -H "Authorization: Bearer ${TOKEN}" \
  "${BASE}/schema/search?q=monthly revenue"

curl -sS \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -X POST "${BASE}/query" \
  -d '{"sql":"SELECT id, total FROM orders ORDER BY created_at DESC"}'

JavaScript

fetch

const token = process.env.CTRLZ_TOKEN;
const baseUrl = "https://app.ctrlz.app/api/developer/v1";

const resp = await fetch(`${baseUrl}/query`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sql: "SELECT id, total FROM orders ORDER BY created_at DESC",
  }),
});

if (!resp.ok) {
  const err = await resp.json();
  throw new Error(`${err.error.code}: ${err.error.message}`);
}

const data = await resp.json();
console.log(data.rows);

Python

requests

import requests

token = "cz_mcp_..."
base_url = "https://app.ctrlz.app/api/developer/v1"

resp = requests.post(
    f"{base_url}/query",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={
        "sql": "SELECT id, total FROM orders ORDER BY created_at DESC",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json()["rows"])

Siguiente nivel de detalle

Cuando necesites payloads exactos, schemas OpenAPI o probar requests desde el navegador, usa la referencia tecnica auto-generada. La guia publica de esta pagina esta pensada para onboarding y decision tecnica rapida.

Abrir Swagger UI Abrir ReDoc

Checklist antes de integrar

1. El tenant debe estar en plan Pro.
2. Debe existir una conexion activa y sana.
3. El token lo crea un admin desde el dashboard.
4. Empieza siempre por metadata antes de consultar.
5. Considera manejar `401`, `403`, `404` y `readonly_violation` desde tu cliente.