API de Clatri

La API de Clatri te deja leer y modificar tus datos de Clatri desde tus propias apps, scripts y automatizaciones, con HTTPS y JSON. Ejecuta las mismas herramientas que usan el agente de Clatri y el Clatri MCP: registrar un gasto, consultar el estado de resultados, crear una tarea, leer tus medicamentos…

Usa el mismo token que el MCP. Si ya tienes uno, no necesitas otra llave.

¿API o MCP?

MCP: si quieres que un asistente de IA (Claude, ChatGPT, Cursor…) consulte tu Clatri mientras conversas con él. Ver Clatri MCP.
API: si escribes código. Tu programa decide qué herramienta llamar y con qué datos, y recibe JSON.

Cómo funciona

URL base: https://api.clatri.com/v1
Autenticación: cabecera Authorization: Bearer clt_mcp_XXXX en cada llamada.
Todo es una herramienta. Para ejecutar una, haces POST a /v1/entities/{entity_id}/tools/{tool_name} con sus argumentos como cuerpo JSON. La entidad (personal, empresa, proyecto) siempre va en la ruta.

Método y ruta	Para qué sirve
`GET /v1/me`	El token: tu usuario, permisos, áreas, entidades y fecha de caducidad.
`GET /v1/entities`	Las entidades que este token puede usar (id, tipo, nombre).
`GET /v1/tools`	Las herramientas que este token puede llamar, con su esquema de entrada.
`POST /v1/entities/{entity_id}/tools/{tool_name}`	Ejecuta una herramienta en esa entidad.
`GET /v1/openapi.json`	La especificación OpenAPI 3.1 completa. Es pública: no necesita token.

La lista completa de herramientas, con sus argumentos, está en la referencia de la API.

Requisitos

Necesitas una suscripción activa de Clatri

Igual que el MCP, la API requiere una suscripción activa. Sin ella no puedes crear tokens, y los que ya existen responden 402 subscription_inactive hasta que la renueves. No se borran: vuelven a funcionar solos al renovar.

Necesitas llamarla desde un servidor o un script

La API no acepta llamadas desde el navegador: no envía cabeceras CORS. Es a propósito, para que nadie ponga tu token en el código de una página web. Llámala desde un backend, un script, una función serverless o una herramienta de automatización.

Paso 1 — Crea tu token

En la app de Clatri, abre Ajustes → Conexiones → Agentes y APIs. En la web, Ajustes → Agentes y APIs.
Toca Crear token y ponle un nombre que reconozcas (por ejemplo, "Mi script de gastos").
Elige los permisos: Solo lectura, Lectura y escritura o Acceso completo (incluye eliminar).
Si quieres, limita las áreas (Dinero, Salud, Administración, General) y las entidades que puede usar. Por defecto tiene todas.
Toca Crear token y cópialo.

Cópialo de inmediato

El token (empieza por clt_mcp_) se muestra una sola vez. Si lo pierdes, revócalo y crea otro. Trátalo como una contraseña: cualquiera que lo tenga puede usar tus datos con los permisos que elegiste.

Los tokens caducan a los 6 meses y puedes tener hasta 10 activos. Después de creado, puedes cambiar su nombre, permisos, áreas y entidades sin generar uno nuevo.

En los ejemplos de esta página el token está en una variable de entorno:

export CLATRI_TOKEN="clt_mcp_XXXX"

Paso 2 — Tu primera llamada

Comprueba que el token funciona con GET /v1/me:

curl
Python
JavaScript

curl https://api.clatri.com/v1/me \
  -H "Authorization: Bearer $CLATRI_TOKEN"

import os
import requests

BASE = "https://api.clatri.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['CLATRI_TOKEN']}"}

me = requests.get(f"{BASE}/me", headers=HEADERS, timeout=30)
me.raise_for_status()
print(me.json())

// Node.js 18 o superior (fetch incluido)
const BASE = "https://api.clatri.com/v1";
const headers = { Authorization: `Bearer ${process.env.CLATRI_TOKEN}` };

const res = await fetch(`${BASE}/me`, { headers });
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
console.log(await res.json());

La respuesta se ve así (datos ficticios):

{
  "user_id": "11111111-1111-4111-8111-111111111111",
  "credential": "personal_token",
  "token_name": "Mi script de gastos",
  "permissions": ["read", "write"],
  "areas": ["money", "administration"],
  "entity_ids": null,
  "entities": [
    {"id": "22222222-2222-4222-8222-222222222222", "type": "personal", "name": "Personal", "is_shared": false},
    {"id": "33333333-3333-4333-8333-333333333333", "type": "business", "name": "Mi empresa", "is_shared": false}
  ],
  "expires_at": "2027-04-29T15:00:00+00:00",
  "request_id": "req_0f1e2d3c4b5a69788796a5b4c3d2e1f0"
}

areas: null significa todas las áreas; entity_ids: null, todas tus entidades.
is_shared: true marca una entidad que otra persona compartió contigo.

Elige la entidad

GET /v1/entities devuelve solo la lista de entidades del token. Guarda el id de la que vas a usar:

curl https://api.clatri.com/v1/entities \
  -H "Authorization: Bearer $CLATRI_TOKEN"

{
  "entities": [
    {"id": "22222222-2222-4222-8222-222222222222", "type": "personal", "name": "Personal", "is_shared": false}
  ],
  "request_id": "req_…"
}

Descubre las herramientas

GET /v1/tools lista lo que este token puede hacer: ya filtra por sus permisos y áreas. Cada herramienta trae su esquema de entrada (JSON Schema):

curl https://api.clatri.com/v1/tools \
  -H "Authorization: Bearer $CLATRI_TOKEN"

{
  "tools": [
    {
      "name": "create_task",
      "title": "Create task",
      "description": "Create a task. …",
      "area": "administration",
      "permission": "write",
      "destructive": false,
      "supports_dry_run": false,
      "requires_confirmation": false,
      "requires_idempotency_key": true,
      "path": "/v1/entities/{entity_id}/tools/create_task",
      "input_schema": {"type": "object", "properties": {"title": {"type": "string"}}, "required": ["title"]}
    }
  ],
  "request_id": "req_…"
}

Los nombres, descripciones y esquemas de las herramientas están en inglés.

Paso 3 — Ejecuta una herramienta

Una lectura

Estado de resultados de septiembre de 2026 (lo ganado y lo gastado) en la entidad personal:

curl
Python
JavaScript

curl -X POST \
  https://api.clatri.com/v1/entities/22222222-2222-4222-8222-222222222222/tools/read_income_statement \
  -H "Authorization: Bearer $CLATRI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"start_date": "2026-09-01", "end_date": "2026-09-30", "include_analytics": false}'

ENTITY = "22222222-2222-4222-8222-222222222222"

res = requests.post(
    f"{BASE}/entities/{ENTITY}/tools/read_income_statement",
    headers=HEADERS,
    json={"start_date": "2026-09-01", "end_date": "2026-09-30", "include_analytics": False},
    timeout=60,
)
res.raise_for_status()
body = res.json()
print(body["text"])

const ENTITY = "22222222-2222-4222-8222-222222222222";

const res = await fetch(`${BASE}/entities/${ENTITY}/tools/read_income_statement`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ start_date: "2026-09-01", end_date: "2026-09-30", include_analytics: false }),
});
const body = await res.json();
console.log(body.text);

Toda respuesta correcta tiene la misma forma:

{
  "data": {"…": "resultado estructurado, cuando la herramienta devuelve JSON"},
  "text": "La respuesta de la herramienta en texto",
  "request_id": "req_6c1d0e2a9b7f4e3c8a5d1f0b2e4c6a8d",
  "idempotent_replay": false
}

Campo	Qué contiene
`data`	El resultado en JSON cuando la herramienta lo devuelve. Si la herramienta solo responde con texto, es `null`.
`text`	La respuesta completa de la herramienta, en texto. Siempre está.
`request_id`	El identificador de la llamada. También llega en la cabecera `Clatri-Request-Id`. Inclúyelo si escribes a soporte.
`idempotent_replay`	`true` cuando es la respuesta guardada de una llamada anterior con la misma `Idempotency-Key` (ver abajo).

nota

No envíes entity_id en el cuerpo: va en la ruta. Un argumento que la herramienta no conoce también se rechaza con 400 validation_error, antes de ejecutar nada.

Una escritura

Las herramientas que crean, editan o eliminan exigen la cabecera Idempotency-Key. Crear una tarea en la entidad personal:

curl
Python
JavaScript

curl -X POST \
  https://api.clatri.com/v1/entities/22222222-2222-4222-8222-222222222222/tools/create_task \
  -H "Authorization: Bearer $CLATRI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0d7f8e-3c2a-4e1b-9f6d-1a2b3c4d5e6f" \
  -d '{"title": "Renovar el seguro del carro", "due_date": "2026-11-15"}'

import uuid

res = requests.post(
    f"{BASE}/entities/{ENTITY}/tools/create_task",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={"title": "Renovar el seguro del carro", "due_date": "2026-11-15"},
    timeout=60,
)
res.raise_for_status()
print(res.json()["text"])

const res = await fetch(`${BASE}/entities/${ENTITY}/tools/create_task`, {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ title: "Renovar el seguro del carro", due_date: "2026-11-15" }),
});
console.log((await res.json()).text);

Permisos, áreas y entidades

Cada token tiene tres límites. Una llamada que se sale de cualquiera de ellos se rechaza antes de ejecutar nada.

Permisos. Cada herramienta pide un permiso:

Permiso en la API	Qué permite	Nivel en la app que lo incluye
`read`	Consultar	Solo lectura, Lectura y escritura, Acceso completo
`write`	Crear y editar	Lectura y escritura, Acceso completo
`delete`	Eliminar o anular	Acceso completo

Sin el permiso → 403 scope_denied.

Áreas. Cada herramienta pertenece a un área:

Área en la app	En la API	Qué incluye
Dinero	`money`	Cuentas, tarjetas, movimientos, deudas, ahorros, inversiones, ventas y contabilidad
Salud	`health`	Afecciones, episodios, medicamentos, fórmulas, métricas y documentos de salud
Administración	`administration`	Espacios, páginas, tableros, tareas, hábitos, calendario, contactos y lugares
General	`general`	Contexto, memoria, documentos, programaciones y actividad

Fuera de las áreas del token → 403 domain_denied.

Entidades. Si limitaste el token a algunas entidades, cualquier otra responde 403 entity_denied. Lo mismo pasa si el cuerpo menciona un registro (una cuenta, una tarea…) de otra entidad.

Dale a cada integración solo lo que necesita

Un script que solo lee gastos no necesita escribir ni ver tu salud. Crea un token Solo lectura, con el área Dinero y la entidad que corresponda. Si algún día se filtra, el daño queda acotado.

Escrituras seguras

Idempotency-Key

Las herramientas con permiso write o delete exigen la cabecera Idempotency-Key. Sin ella → 400 idempotency_key_required.

Genera un valor único por operación (un UUID sirve; de 1 a 255 caracteres ASCII visibles) y reutilízalo si repites esa misma operación, por ejemplo tras un corte de red. Así un reintento no registra el gasto dos veces:

Situación	Resultado
Misma clave y mismo cuerpo, la primera llamada ya terminó	Recibes la respuesta guardada, con `idempotent_replay: true`. No se ejecuta otra vez.
Misma clave con otro cuerpo, otra herramienta u otra entidad	`409 idempotency_key_reused`
Misma clave mientras la primera llamada sigue en curso	`409 idempotency_in_progress`, con `Retry-After`

Una clave vale para el token que la usó y se recuerda durante 24 horas.
Si la primera llamada terminó con un error del servidor (5xx), la clave se libera y puedes reintentar con la misma.
Las lecturas no necesitan clave.

Vista previa con `?dry_run=true`

Algunas herramientas pueden mostrarte el resultado sin guardar nada. Son las que en GET /v1/tools tienen supports_dry_run: true. Agrega ?dry_run=true a la URL:

curl -X POST \
  "https://api.clatri.com/v1/entities/22222222-2222-4222-8222-222222222222/tools/record_consumable_balance_observation?dry_run=true" \
  -H "Authorization: Bearer $CLATRI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"balance_identifier": "Tarjeta de transporte", "observed_amount": 25000, "source": "api"}'

Con ?dry_run=true la herramienta solo calcula (preview: true), aunque el cuerpo diga otra cosa.
Una vista previa no necesita Idempotency-Key y su respuesta no se guarda.
En una herramienta sin vista previa, ?dry_run=true responde 400 dry_run_not_supported: nunca se ejecuta "de verdad" por error.

Confirmar borrados con `?confirm=true`

Las herramientas con permiso delete (eliminar o anular datos) exigen ?confirm=true en la URL, además de la Idempotency-Key. Sin la confirmación → 428 confirmation_required y no se borra nada:

curl -X POST \
  "https://api.clatri.com/v1/entities/22222222-2222-4222-8222-222222222222/tools/delete_task?confirm=true" \
  -H "Authorization: Bearer $CLATRI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a" \
  -d '{"task_id": "44444444-4444-4444-8444-444444444444"}'

En GET /v1/tools estas herramientas tienen requires_confirmation: true. El campo destructive: true marca además las que sobrescriben datos.

Errores

Los errores llegan como application/problem+json (RFC 9457), siempre con un code estable que puedes usar en tu código:

{
  "type": "https://docs.clatri.com/api/errors#scope_denied",
  "title": "Permission not granted",
  "status": 403,
  "detail": "This token does not have the permission this tool requires.",
  "code": "scope_denied",
  "request_id": "req_6c1d0e2a9b7f4e3c8a5d1f0b2e4c6a8d"
}

title y detail están en inglés y pueden cambiar de redacción: decide con code y status.

HTTP	Códigos
400	`validation_error`, `idempotency_key_required`, `dry_run_not_supported`, `https_required`
401	`unauthorized`, `token_revoked`, `token_expired`
402	`subscription_inactive`
403	`scope_denied`, `domain_denied`, `entity_denied`
404	`tool_not_found`, `tool_not_available`, `not_found`
405	`method_not_allowed`
409	`idempotency_key_reused`, `idempotency_in_progress`
413	`payload_too_large`
422	`tool_error`
428	`confirmation_required`
429	`rate_limited`
500	`internal_error`
503	`service_unavailable`

Qué significa cada código y qué hacer: Errores de la API.

422 tool_error es el más común en el día a día: la herramienta se ejecutó pero no pudo completar lo que pediste (por ejemplo, una cuenta que no existe). El detail explica el motivo.

Límites

Límite	Valor
Lecturas por token	120 por minuto
Escrituras y borrados por token	30 por minuto
Llamadas por entidad (todos los tokens juntos)	300 por minuto
Tamaño máximo del cuerpo	256 KB

Las ventanas son de un minuto fijo. GET /v1/me, /v1/entities y /v1/tools cuentan como lecturas del token.
Las respuestas traen RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (segundos hasta que se reinicia la ventana). Si aplican varios límites, las cabeceras muestran el más cercano a agotarse.
Al pasarte recibes 429 rate_limited con Retry-After en segundos. Espera ese tiempo antes de reintentar.
Bloqueo por fallos repetidos: 20 respuestas 401 o 403 en 5 minutos, para un mismo token o una misma IP, bloquean ese token o esa IP durante 15 minutos (429 con Retry-After). Si tu script recibe un 401 o un 403, corrige la causa en lugar de reintentar en bucle.
Algunas herramientas (búsqueda web, mapas, imágenes) consumen créditos de tu cuenta, como cuando las usa el agente.

Cabeceras útiles

Cabecera	Dónde	Para qué
`Authorization: Bearer …`	Petición	Tu token. Obligatoria salvo en `/v1/openapi.json`.
`Idempotency-Key`	Petición	Obligatoria en escrituras y borrados.
`Content-Type: application/json`	Petición	En las llamadas con cuerpo.
`Clatri-Request-Id`	Respuesta	Identificador de la llamada, en todas las respuestas.
`RateLimit-*`, `Retry-After`	Respuesta	Límites de tasa (ver arriba).

La API solo funciona por HTTPS. Las respuestas llevan Cache-Control: no-store.

Versionado y deprecación

La versión va en la ruta: /v1. Un cambio que rompa la compatibilidad sale como una versión nueva.
Antes de retirar una versión, sus respuestas llevan las cabeceras Deprecation y Sunset, con al menos 90 días de aviso.
Los códigos de error son parte del contrato: pueden aparecer códigos nuevos, pero los existentes no se renombran ni se eliminan dentro de v1.
Las herramientas son las mismas del agente de Clatri, así que el catálogo crece con el producto. Consulta GET /v1/tools o la referencia para ver el esquema vigente.

Seguridad

Cuida tu token

Nunca lo compartas ni lo pegues en chats, capturas, tickets o foros.
No lo subas a un repositorio ni lo pongas en el código de una app móvil o una página web. Guárdalo en una variable de entorno o en un gestor de secretos.
Un token por integración. Así puedes revocar uno sin afectar a los demás y ves en la actividad qué hizo cada uno.
Si se filtró, revócalo en Ajustes → Conexiones → Agentes y APIs. La revocación es inmediata. Luego crea otro.

Qué puede y qué no puede hacer un token

Un token solo actúa dentro de Clatri, con los permisos, áreas y entidades que le diste. No puede crear otros tokens, cambiar tu contraseña o tu correo, tocar tu suscripción, borrar una entidad ni ver entidades fuera de su alcance.

Cada llamada a una herramienta queda en la actividad reciente del token (Ajustes → Conexiones → Agentes y APIs → toca el token), igual que las del MCP. Si ves algo que no reconoces, revócalo.

Herramientas que no están disponibles por API

Algunas herramientas del agente no se pueden llamar por la API aunque el token tenga permiso. Responden 404 tool_not_available y no aparecen en GET /v1/tools ni en la referencia:

Consultas libres a la base de datos. No son un contrato estable ni revisable.
Contraseñas de documentos. Guardar o usar la contraseña de un PDF protegido es manejo de credenciales.
Gestión de accesos. Invitar o quitar miembros de un espacio, ver quién más está en él, o vincular un contacto con otra cuenta de Clatri: cambian quién ve tus datos.
Buscar otras entidades o personas. Un token nunca ve entidades fuera de las suyas.
Programaciones. Crear, editar o ejecutar una programación pone a trabajar después al agente completo con todos tus permisos, por fuera de los límites del token.
whoami y list_entities del MCP: en la API los reemplazan GET /v1/me y GET /v1/entities.

Para estas acciones usa la app o el chat de Clatri.

Si conectas la API a un modelo de IA

Lo que devuelve la API son tus datos: descripciones de movimientos, textos de documentos, notas. Si se los pasas a un modelo de IA, trátalos como datos, no como instrucciones. Un texto dentro de un documento podría intentar darle órdenes al modelo.

Tokens OAuth de apps conectadas

Además de los tokens personales (clt_mcp_), la API acepta los tokens de acceso OAuth (clt_at_) que reciben las apps a las que conectaste Clatri por OAuth. Esos tokens solo ven el catálogo reducido de herramientas que esas apps usan en el MCP.

Referencia de la API

Referencia interactiva: todas las herramientas, con sus argumentos, permisos, áreas y ejemplos de cuerpo.
OpenAPI 3.1: https://api.clatri.com/v1/openapi.json (pública, siempre al día). Impórtala en Postman, Insomnia o tu generador de clientes.
Errores de la API: cada código, su causa y qué hacer.

Cómo funciona​

Requisitos​

Paso 1 — Crea tu token​

Paso 2 — Tu primera llamada​

Elige la entidad​

Descubre las herramientas​

Paso 3 — Ejecuta una herramienta​

Una lectura​

Una escritura​

Permisos, áreas y entidades​

Escrituras seguras​

Idempotency-Key​

Vista previa con ?dry_run=true​

Confirmar borrados con ?confirm=true​

Errores​

Límites​

Cabeceras útiles​

Versionado y deprecación​

Seguridad​

Referencia de la API​