Usar la API

Todas las apps de Kombine se comunican con una única API REST. Con un token de acceso personal, tus propias herramientas también pueden usarla. Todo lo que hay aquí funciona con curl y jq.

• URL base: https://api.kombine.dev/v1
• Autenticación: envía el token como Authorization: Bearer kmb_pat_…
• Formato: JSON de entrada, JSON de salida. Las horas van en ISO 8601 (2026-10-23T09:00:00Z).
• Referencia completa: la especificación OpenAPI lista todos los endpoints y campos. Pégala en cualquier visor de OpenAPI o pásasela a tu agente de IA.

Configura tu shell una vez:

export KOMBINE_TOKEN='kmb_pat_…'
export API='https://api.kombine.dev/v1'
k() { curl -sS -H "Authorization: Bearer $KOMBINE_TOKEN" -H 'Content-Type: application/json' "$@"; }

Los ejemplos de abajo usan esa función auxiliar k.

Tareas

Necesita tasks: Lectura para listar y Lectura y escritura para hacer cambios.

Listar tareas. Los resultados llegan por páginas dentro de data, con total, limit (200 por defecto, máximo 500) y offset:

k "$API/tasks?limit=500" | jq '.data[] | {title, status, priority, due_date}'

No hay filtro en el servidor por estado o fecha, así que filtra con jq. Tareas abiertas que vencen hoy o antes:

today=$(date +%F)
k "$API/tasks?limit=500" | jq -r --arg d "$today" '
  .data[] | select(.status != "DONE" and .is_archived == false and .due_date != null and .due_date[0:10] <= $d)
  | "\(.priority // "-")\t\(.title)"'

Añadir una tarea. Tu herramienta elige el id de la tarea (cualquier UUID), igual que hacen las apps. Así los reintentos son seguros: enviar el mismo id dos veces no puede crear dos tareas.

k -X POST "$API/tasks" -d "$(jq -n --arg id "$(uuidgen | tr A-Z a-z)" '{
  id: $id,
  title: "Renew passport",
  priority: "HIGH",
  due_date: "2026-11-01T00:00:00Z",
  due_date_has_time: false,
  tags: ["errands"]
}')"

• priority: LOW, MEDIUM o HIGH (omítelo si no quieres prioridad)
• status: TODO (por defecto), IN_PROGRESS o DONE
• due_date_has_time: false significa “vence ese día”, sin hora

Cambiar una tarea. PUT cambia solo los campos que envías. Marca una como hecha:

k -X PUT "$API/tasks/$TASK_ID" -d '{"status":"DONE"}'

Completar una tarea por la API cuenta igual que en las apps: se registra en tus estadísticas y una tarea repetitiva pasa a su siguiente fecha.

Sesiones de concentración

Necesita sessions: Lectura y escritura. Registra una sesión que hiciste en otro sitio (una reunión, una carrera, tiempo medido en otra app):

k -X POST "$API/sessions" -d "$(jq -n --arg id "$(uuidgen | tr A-Z a-z)" '{
  id: $id,
  mode: "POMODORO",
  started_at: "2026-10-23T07:00:00Z",
  ended_at: "2026-10-23T07:25:00Z",
  duration_ms: 1500000,
  note: "Pairing on the importer"
}')"

mode es POMODORO, FLOW o ADAPTIVE. Añade task_id o activity_id para etiquetarla. Lista tus actividades con k "$API/activities" | jq '.data[] | {id, name}'.

Temporizador

Necesita timer: Lectura. Mira qué está en marcha en cualquiera de tus dispositivos:

k "$API/timer/state" | jq '{status, mode, is_break, started_at, elapsed_ms, task_id}'

Una respuesta vacía (204) significa que no hay ningún temporizador en marcha.

No se recomienda iniciar o detener el temporizador desde un script. Solo la app que ejecutó el temporizador registra la sesión, así que un temporizador iniciado por la API no deja ninguna sesión. Para registrar tiempo, registra una sesión (consulta Sesiones de concentración más arriba).

Estadísticas

Necesita stats: Lectura.

k "$API/stats/all-time" | jq '{totalFocusSessions, hours: ((.totalFocusSeconds // 0) / 3600 | floor), longestStreakLength}'
k "$API/daily-snapshots?from=2026-10-01&to=2026-10-31" | jq '.snapshots[] | {date, sessions_completed, achieved}'

Las estadísticas históricas se calculan en segundo plano. En una cuenta recién creada, stats/all-time responde 404 (“No stats available yet”) hasta que se calculan por primera vez.

Errores

Los errores son JSON con un error_code que puedes comprobar, por ejemplo:

{ "title": "Forbidden", "status": 403, "detail": "Personal access token does not permit this route", "error_code": 1014 }

Estado	error_code	Significado	Qué hacer
400	5001, 5002	Falta un campo o no es válido; errors indica cuál	Corrige la petición
401	1013	El token ha caducado	Crea un token nuevo
401	1011	El token ha sido revocado	Crea un token nuevo
401	1004	Token no reconocido	Comprueba que lo copiaste entero
403	1014	Los permisos del token no cubren esto	Crea un token con los permisos adecuados
409	4003	Ese id ya está en uso	Puedes ignorarlo sin problema en un reintento
409	4010	Ese external_ref ya está en uso	Consulta Flujos de trabajo
429	6001	Demasiadas peticiones	Espera Retry-After segundos

GET /v1/error-codes los lista todos (no hace falta token).

Límites

Cada token tiene 60 peticiones por minuto, con ráfagas cortas de hasta 20. Si te pasas, recibes 429 con una cabecera Retry-After. Los demás tokens y tus apps no se ven afectados.