API de búsqueda

Búsqueda de texto completo

GET /api/search/

Busca nodos por título y contenido con ordenación por relevancia mediante BM25.

Parámetros:

Parámetro	Tipo	Obligatorio	Valor predeterminado	Descripción
q	string	sí	—	Consulta de búsqueda
connection_id	UUID	no	primera conexión del usuario	Conexión específica en la que buscar
size	int	no	50	Número máximo de resultados
highlight	bool	no	true	Incluir fragmentos con coincidencias resaltadas
type	string	no	all	Filtro: page, database o user

Ejemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/?q=project+planning&size=10"

import requests

resp = requests.get(
    "https://ivgraph.com/api/search/",
    headers={"Authorization": "Bearer <jwt_token>"},
    params={"q": "project planning", "size": 10}
)
results = resp.json()["results"]

const resp = await fetch(
  "https://ivgraph.com/api/search/?q=project+planning&size=10",
  { headers: { Authorization: "Bearer <jwt_token>" } }
);
const { results } = await resp.json();

Respuesta:

{
  "query": "project planning",
  "total": 8,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "page",
      "title": "Project Planning Guide",
      "score": 12.5,
      "highlight": "...comprehensive <em>project</em> <em>planning</em> methodology..."
    }
  ]
}

Autocompletado

GET /api/search/suggest/

Autocompletado basado en prefijos para buscar mientras escribes.

Parámetros:

Parámetro	Tipo	Obligatorio	Valor predeterminado	Descripción
q	string	sí	—	Prefijo (mínimo 2 caracteres)
size	int	no	10	Número máximo de sugerencias

Ejemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/suggest/?q=pro"

Respuesta:

{
  "prefix": "pro",
  "suggestions": [
    {"id": "uuid-1", "title": "Project Alpha", "type": "page"},
    {"id": "uuid-2", "title": "Product Roadmap", "type": "page"},
    {"id": "uuid-3", "title": "Projects Tracker", "type": "database"}
  ]
}

Búsqueda semántica

GET /api/search/semantic/

Búsqueda por similitud vectorial mediante representaciones vectoriales. Encuentra contenido conceptualmente similar, no solo coincidencias de palabras clave.

Parámetros:

Parámetro	Tipo	Obligatorio	Valor predeterminado	Descripción
q	string	sí	—	Consulta en lenguaje natural
connection_id	UUID	no	primera conexión del usuario	Conexión en la que buscar
size	int	no	10	Número máximo de resultados

Ejemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/semantic/?q=how+do+we+handle+user+onboarding"

Respuesta:

{
  "query": "how do we handle user onboarding",
  "total": 5,
  "search_type": "semantic",
  "results": [
    {"id": "uuid-1", "type": "page", "title": "New User Welcome Flow", "score": 0.89},
    {"id": "uuid-2", "type": "page", "title": "Onboarding Checklist", "score": 0.82}
  ]
}

Búsqueda híbrida

GET /api/search/hybrid/

Combina la búsqueda por palabras clave mediante BM25 con la búsqueda semántica vectorial para obtener resultados que aprovechan lo mejor de ambas.

Parámetros: Los mismos que en la búsqueda semántica.

Ejemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/hybrid/?q=authentication+flow"

Nodos similares

GET /api/search/similar/{node_id}/

Encuentra nodos similares a un nodo dado mediante representaciones vectoriales.

Parámetros:

Parámetro	Tipo	Obligatorio	Valor predeterminado	Descripción
node_id	UUID	sí	—	ID del nodo de origen (en la ruta de la URL)
connection_id	UUID	no	primera conexión del usuario	Conexión en la que buscar
size	int	no	10	Número máximo de resultados

Ejemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/similar/550e8400-e29b-41d4-a716-446655440001/"

Contenido de la página

GET /api/search/content/{page_id}/

Obtén el contenido de una página en Markdown y texto sin formato.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
page_id	UUID	sí	ID de la página (en la ruta de la URL)

Ejemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/content/550e8400-e29b-41d4-a716-446655440001/"

Respuesta:

{
  "page_id": "550e8400-e29b-41d4-a716-446655440001",
  "title": "Project Alpha",
  "markdown": "# Project Alpha\n\nMain project page...",
  "plain_text": "Project Alpha\nMain project page...",
  "has_content": true
}

Gestión de índices

POST /api/search/index/

Inicia la reindexación del índice de Elasticsearch para la conexión del usuario.

curl -X POST -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/index/"

Respuesta:

{"message": "Indexing complete", "index_name": "ivg_conn-uuid", "indexed_count": 342}

DELETE /api/search/index/

Elimina el índice de búsqueda de la conexión del usuario.

curl -X DELETE -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/index/"

GET /api/search/connections/

Enumera todos los índices de búsqueda del usuario.

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/connections/"

Respuesta:

{
  "user": "username",
  "connections": [
    {
      "connection_id": "conn-uuid",
      "schema_name": "airbyte_conn_uuid",
      "index_name": "ivg_conn-uuid",
      "document_count": 342,
      "last_sync": "2026-04-10T10:00:00Z"
    }
  ]
}

Errores

Estado	Significado
400	Faltan parámetros de consulta o no son válidos
401	Sin autenticar
404	No se ha encontrado la conexión o la página
503	Elasticsearch no está disponible