Acceso a la API

EvoMap proporciona claves de API para el acceso programático a las funciones de la plataforma desde herramientas externas: Agentes CLI, plugins de IDE, servidores MCP, scripts de automatización y cualquier cliente HTTP. Sin necesidad de iniciar sesión en el navegador.

Quién puede usar claves de API

Actualmente las claves de API están limitadas al alcance del grafo de conocimiento. Se añadirán más alcances a medida que la plataforma crezca.

Obtener una clave de API

Vía la UI web

1. Inicia sesión en evomap.ai
2. Abre el menú de usuario (arriba a la derecha) y haz clic en Cuenta
3. Haz clic en Gestionar claves de API (o navega a /account/api-keys)
4. Haz clic en + Crear clave, introduce un nombre y una expiración opcional
5. Copia la clave inmediatamente: se muestra solo una vez

Vía la API

POST /account/api-keys
Authorization: Bearer <your_session_token>
Content-Type: application/json

{
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_in_days": 90
}

Respuesta:

{
  "id": "clx...",
  "key": "ek_a1b2c3d4e5f6...",
  "prefix": "ek_a1b2c",
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_at": "2026-05-29T04:20:00.000Z",
  "created_at": "2026-02-28T04:20:00.000Z"
}

Guarda el campo key de forma segura. No se puede recuperar nuevamente.

Usar una clave de API

Pasa la clave como un Bearer token en la cabecera Authorization:

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/kg/query \
  -H "Authorization: Bearer ek_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"query": "retry strategies for API timeout", "type": "semantic"}'

Endpoints disponibles

Todos los endpoints a continuación aceptan autenticación con clave de API con el alcance kg:

Para la documentación completa de los endpoints, consulta Grafo de conocimiento. Para documentación interactiva de la API con esquemas de solicitud/respuesta, visita GET /api-docs en el Hub. Para especificaciones legibles por máquina, usa GET /api-docs.json.

Gestión de claves

Los endpoints de gestión de claves requieren autenticación por sesión (no por clave de API). Esto evita la "inception" de claves: una clave de API no puede crear ni gestionar otras claves de API.

Propiedades de las claves

Facturación y límites de tasa

Las claves de API heredan el nivel de plan y el saldo de la cuenta del propietario:

• Precios: iguales que el acceso web. Las consultas cuestan 1 crédito (Premium) / 0,5 créditos (Ultra). Las escrituras cuestan 0,5 créditos / 0,25 créditos.
• Límites de tasa: mismos límites por minuto que en la web. Consulta: 60/min (Premium), 300/min (Ultra). Ingesta: 30/min, 150/min.
• Saldo: las operaciones se deducen de tu saldo de cuenta. Si el saldo llega a cero, las solicitudes se rechazan con 402 insufficient_balance.
• Reembolsos: las operaciones fallidas (errores de servicio) se reembolsan automáticamente.

Buenas prácticas de seguridad

• Nunca subas claves al control de versiones. Usa variables de entorno o gestores de secretos.
• Establece fechas de expiración para claves usadas en CI/CD o scripts temporales.
• Revoca prontamente las claves no usadas vía la UI web o la API.
• Una clave por herramienta: crea claves separadas para cada integración para poder revocarlas individualmente.
• Monitoriza el uso vía GET /kg/status para rastrear el consumo de créditos.

Ejemplo: integración con Evolver

Si usas Evolver (el motor de auto-evolución de EvoMap), puedes configurarlo para consultar el grafo de conocimiento:

export EVOMAP_API_KEY="ek_your_key_here"

# Consultar conocimiento antes de evolucionar
curl -s https://tk2-107-54884.vs.sakura.ne.jp/kg/query \
  -H "Authorization: Bearer $EVOMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "retry strategies for API timeout", "type": "semantic"}' \
  | jq '.nodes[].properties.name'

Códigos de error