---
id: 0012
title: Endpoint HTTP local de ingesta y consulta
status: pending
priority: medium
created: 2026-05-01
---

## Objetivo

Exponer un servidor HTTP local en `graph_explorer` (o como `ingest_server`
hermano) que sea el punto de entrada unico para todo flujo externo:
extension de navegador, CLI `gx`, watcher de portapapeles, bots, OCR, etc.

Sin este endpoint cada cliente externo tendria que abrir `operations.db`
directamente — colisiona con el lock del proceso vivo y duplica logica de
extraccion.

## Endpoints minimos

- `POST /entity` — crea entidad. Body: `{type, name, metadata}`.
- `POST /relation` — crea relacion. Body: `{from_id, to_id, kind, metadata}`.
- `POST /ingest/text` — texto libre -> `extract_graph_hybrid` -> preview o auto-commit.
- `POST /ingest/url` — URL -> fetch + extract -> preview o auto-commit.
- `POST /ingest/file` — multipart upload (PDF/CSV/JSON/.eml/imagen) -> router por mime -> extract.
- `GET  /search?q=` — fuzzy / FTS sobre entidades.
- `GET  /entity/:id`, `GET /entity/:id/neighbors`.

## Decisiones

- Bind a `127.0.0.1` por defecto, puerto fijo (ej. 7878) o aleatorio
  escrito a `~/.fn_graph_port`.
- Auth: token compartido en `~/.fn_graph_token` (header `X-Token`).
  Generado al primer arranque.
- Modo "preview": las rutas de ingesta aceptan `?commit=false` y
  devuelven entities/relations propuestas para que el cliente las muestre
  antes de persistir. Cuando es `true`, escribe directo.
- Implementacion: httplib o Mongoose embebido en C++ (sin nuevas deps
  pesadas). Alternativa: lanzar el servidor en Go/Python aparte si la
  integracion C++ se complica.

## Bloquea

Issues 0014, 0017, 0018, 0019, 0020 dependen de este.

## Definicion de hecho

- `curl -H "X-Token: ..." -d '{"type":"person","name":"X"}' localhost:7878/entity`
  crea entidad.
- `POST /ingest/text` con texto en castellano devuelve entities/relations
  detectadas por el pipeline hibrido.
- El endpoint corre en background mientras la UI sigue interactiva.
- Si `graph_explorer` no esta abierto, un binario `ingest_server`
  standalone ofrece el mismo API contra la misma `operations.db`.