API REST

Truke KF ofrece una pequeña API REST/JSON bajo /api. Con ella puede leer un ítem, realizar una búsqueda de texto completo, recorrer las relaciones entre ítems y crear o actualizar ítems y sus objetos relacionados (eventos, acciones, componentes, etc.) — todo lo que la interfaz web hace con el almacén de ítems, pero desde un script o una integración.

La API concede exactamente su propio acceso: una petición hecha con su token ve los mismos ítems que vería en el navegador, ni uno más. Consulte autenticación y acceso para saber cómo funcionan la identidad y las etiquetas de acceso.

Documentación interactiva

La especificación completa se puede explorar y probar desde el navegador:

Dirección	Qué es
`/api/docs`	Swagger UI — pruebe cada endpoint de forma interactiva
`/api/openapi.yaml`	el documento OpenAPI 3.0 en bruto

Abra /api/docs, pulse Authorize, pegue un token (más abajo) y podrá invocar cualquier endpoint directamente desde la página.

Autenticación

Todos los endpoints de datos requieren un token de acceso personal enviado como credencial bearer:

Authorization: Bearer

Sólo /api/health, /api/docs y /api/openapi.yaml son públicos — todo lo demás devuelve 401 sin un token válido.

Crear un token (debe haber iniciado sesión). El texto en claro se muestra una sola vez — guárdelo de inmediato, no se puede recuperar después:

curl -X POST https://kf.example.com/auth/tokens \
  -d name=mi-script -d ttl=720h
# {"id":"a1b2c3d4","token":"f0e1d2…"}

name es una etiqueta para su propia referencia; ttl es una duración opcional (por ejemplo 720h para 30 días) — omítala para un token que nunca caduca. Para revocar un token use POST /auth/tokens/{id}/revoke. Consulte tokens de acceso para todos los detalles.

¿Cuánto tiempo es válido un token? El que usted decida. A diferencia de la

sesión del navegador (que caduca tras un periodo fijo, 24 horas por defecto),

un token de API no tiene duración por defecto ni máxima — vive exactamente el

ttl que fije al crearlo, o para siempre si lo omite. Una vez emitido, la única

forma de terminarlo antes de tiempo es revocarlo.

ttl debe usar las unidades de duración de Go — h (horas), m (minutos),

s (segundos); por ejemplo 720h, no 30d. Un valor que KF no pueda interpretar

se trata como sin caducidad, de modo que un error como 30d produce en

silencio un token que nunca caduca.

Convenciones

Todos los cuerpos de petición y respuesta son JSON; envíe Content-Type: application/json en POST y PUT.
Un ítem se identifica por su id (o uid). Los ítems también tienen un código legible opcional (un SKU o número x0) y una lista de etiquetas separadas por espacios.
Cada ítem tiene una clase: m (módulo), i (ítem), e (evento), a (acción), t (tipo). La clase determina cómo se comporta y cómo se muestra el ítem.
Los errores se devuelven como { "error": "…" } con el estado HTTP apropiado (400 entrada no válida, 401 token ausente o no válido, 404 no encontrado).

Endpoints

Método y ruta	Propósito
`GET /api/health`	Comprobación de disponibilidad (público, sin token)
`GET /api/search?q=…`	Búsqueda de texto completo (BM25)
`POST /api/items`	Crear un ítem
`GET /api/items/{id}`	Obtener un ítem por su id
`PUT /api/items/{id}`	Actualizar un ítem
`GET /api/items/by-code/{code}`	Obtener un ítem por su código (SKU / x0)
`GET /api/items/by-tag/{tag}`	Listar los ítems con una etiqueta
`GET /api/items/{id}/path`	Ruta (migas) de un ítem
`GET /api/items/{id}/{relation}`	Listar ítems relacionados
`POST /api/items/{id}/{relation}`	Crear y enlazar un ítem relacionado

Búsqueda

GET /api/search?q=fallo+bomba

Búsqueda de texto completo sobre todos los ítems, ordenada por relevancia BM25 (la mejor coincidencia primero). La consulta usa la sintaxis FTS5: palabras clave simples, "frases exactas", comodines prefijo* y los operadores booleanos

AND / OR / NOT.

curl -G https://kf.example.com/api/search \
  --data-urlencode "q=bomba AND (sello OR rodamiento)" \
  -H "Authorization: Bearer $TOKEN"

Cada resultado es una referencia compacta:

[
  { "id": "3k9", "title": "Fuga en el sello de la bomba", "type": "e", "link": "/3k9" }
]

Leer un ítem

GET /api/items/{id} devuelve el ítem completo:

{
  "id": "3k9",
  "uid": "…",
  "title": "Bomba centrífuga",
  "class": "i",
  "code": "PMP-100",
  "tags": "crítico rotativo",
  "parent": "1a2",
  "doc": "Cuerpo del ítem en Markdown…"
}

También puede obtenerlo por código (GET /api/items/by-code/PMP-100) o listar todos los ítems con una etiqueta (GET /api/items/by-tag/crítico).

GET /api/items/{id}/path devuelve el rastro de migas:

{ "id": "3k9", "path": "Inicio / Máquina / Bomba" }

Navegar por las relaciones

GET /api/items/{id}/{relation} lista los ítems enlazados a un ítem por una relación dada. {relation} es una de:

Relación	Sentido	Qué lista
`events`	abajo	modos de fallo / problemas anotados en el ítem
`components`	abajo	sub-partes (lista de materiales)
`actions`	abajo	acciones correctivas / preventivas
`outputs`	abajo	resultados esperados
`instances`	abajo	ítems que aprenden de éste como tipo
`sidebar`	abajo	elementos de navegación de la barra lateral
`causes`	arriba	causas que conducen a este evento
`types`	arriba	tipos de los que aprende este ítem

curl https://kf.example.com/api/items/3k9/events \
  -H "Authorization: Bearer $TOKEN"

Crear y actualizar ítems

Crear un ítem con POST /api/items. Sólo title es obligatorio; class,

code, tags, doc y parent son opcionales:

curl -X POST https://kf.example.com/api/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Bomba centrífuga","class":"i","code":"PMP-100","tags":"crítico"}'

La respuesta es el ítem creado (HTTP 201), incluido su nuevo id.

Actualizar con PUT /api/items/{id}. Sólo se modifican los campos que envíe (title, doc, code, tags); lo que se omite se conserva tal cual.

Crear un ítem relacionado

POST /api/items/{id}/{relation} crea un ítem nuevo de la clase que implica la relación y lo enlaza a {id} en un solo paso. Por ejemplo, para anotar un evento de fallo en un componente:

curl -X POST https://kf.example.com/api/items/3k9/events \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Fuga del sello bajo carga"}'

Las relaciones hacia abajo (events, components, actions, outputs,

instances, sidebar) enlazan el nuevo ítem por debajo de {id}; las relaciones hacia arriba (causes, types) lo enlazan por encima. El cuerpo tiene la misma forma NewItem que POST /api/items, pero class y parent se ignoran — la relación decide ambos.

Una sesión mínima

export TOKEN=f0e1d2…

# encontrar un ítem
curl -G https://kf.example.com/api/search --data-urlencode "q=bomba" \
  -H "Authorization: Bearer $TOKEN"

# leerlo
curl https://kf.example.com/api/items/3k9 -H "Authorization: Bearer $TOKEN"

# anotar un evento de fallo en él
curl -X POST https://kf.example.com/api/items/3k9/events \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Agarrotamiento del rodamiento"}'