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.
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.
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…"}
(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](/es/products/kf/auth) 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
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
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
{
"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`).
!g