Documentación de la API de IVGraph

URL base

Entorno	URL
Producción	https://ivgraph.com/api/
Producción (V1)	https://ivgraph.com/v1/

Autenticación

IVGraph admite dos métodos de autenticación:

Método	Caso de uso	Cabecera
JWT (OAuth de Notion)	Aplicaciones web, sesiones de usuario	Authorization: Bearer <jwt_access_token>
Token de servicio	Agentes LLM, automatización, CI/CD	Authorization: Bearer ivg_<token>

Inicio rápido con un token de servicio

1. Inicia sesión en ivgraph.com mediante OAuth de Notion
2. Ve a Perfil → Tokens de servicio
3. Crea un token con los ámbitos necesarios (p. ej., graph:search, graph:read)
4. Usa el token en tus solicitudes:

curl -H "Authorization: Bearer ivg_your_token_here" \
  "https://ivgraph.com/v1/graph/search?q=project&workspace_id=YOUR_WORKSPACE_ID"

Capas de la API

Capa	Ruta base	Autenticación	Descripción
API V1 para LLM	/v1/graph/	Token de servicio	Acceso de solo lectura al grafo para agentes LLM
API de grafos	/api/notion-graph/	JWT	Datos completos del grafo (nodos + aristas)
API de búsqueda	/api/search/	JWT	Búsqueda de texto completo, semántica e híbrida
API interna	/api/	JWT	Autenticación, facturación, integraciones, reglas de estilo
Pública	/api/stats/public/	Ninguna	Estadísticas de la plataforma, comprobaciones de estado

Límites de solicitudes

API	Límite	Ámbito
V1 (token de servicio)	20 solicitudes/10s en ráfaga, 600 solicitudes/15min	Por token
API de usuario (JWT)	100 solicitudes/min	Por usuario
Acceso anónimo	20 solicitudes/min	Por IP

Formato de los errores

Todos los errores se devuelven en formato JSON:

{
  "error": "Short error message",
  "detail": "Extended description (optional)"
}

Consulta Errores y límites de solicitudes para ver la referencia completa de errores.

Para agentes LLM

Documentación legible por máquinas:

• ivgraph.com/llms.txt — resumen conciso de la API
• ivgraph.com/llms-full.txt — documentación completa con ejemplos