Visión General de la API - Archyl Docs

Aprende sobre la API de Archyl y cómo integrar con tus herramientas y flujos de trabajo

Visión General de la API

Archyl proporciona una API completa que te permite integrar la documentación de arquitectura en tus flujos de trabajo, herramientas y pipelines de automatización.

Endpoints de la API

Archyl ofrece dos interfaces de API:

API REST

La API REST proporciona acceso completo a todas las funciones de Archyl:

  • Crear y gestionar proyectos
  • Agregar, actualizar y eliminar elementos de arquitectura
  • Gestionar relaciones
  • Manejar ADRs y documentación
  • Exportar diagramas

URL Base: https://api.archyl.com/api/v1

Servidor MCP

El servidor Model Context Protocol (MCP) permite que los asistentes de IA interactúen con tu arquitectura:

  • Claude Code, Claude Desktop
  • Cursor
  • VS Code con Copilot
  • Otras herramientas compatibles con MCP

Endpoint SSE: https://api.archyl.com/sse Endpoint HTTP: https://api.archyl.com/mcp

Autenticación

Todas las solicitudes de API requieren autenticación usando una clave API:

curl -H "X-API-Key: tu-clave-api" \
  https://api.archyl.com/api/v1/projects

Creando Claves API

  1. Ve a tu Perfil → Claves API
  2. Haz clic en "Crear Clave API"
  3. Elige permisos (solo lectura o lectura-escritura)
  4. Copia y almacena tu clave de forma segura

Permisos de Claves

Permiso Descripción
Lectura Ver proyectos, elementos y documentación
Escritura Crear y modificar proyectos, elementos, relaciones

Inicio Rápido

Listar Tus Proyectos

curl -X GET \
  -H "X-API-Key: tu-clave-api" \
  https://api.archyl.com/api/v1/projects

Crear un Sistema

curl -X POST \
  -H "X-API-Key: tu-clave-api" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plataforma E-commerce",
    "description": "Sistema principal de e-commerce",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

Crear una Relación

curl -X POST \
  -H "X-API-Key: tu-clave-api" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "system-1",
    "targetId": "system-2",
    "label": "Envía pedidos a",
    "technology": "REST/HTTPS"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/relationships

Manejo de Errores

Los errores de API devuelven códigos de estado HTTP estándar:

Código Descripción
400 Solicitud Inválida - Parámetros inválidos
401 No Autorizado - Clave API inválida o faltante
403 Prohibido - Permisos insuficientes
404 No Encontrado - El recurso no existe
500 Error Interno del Servidor

Las respuestas de error incluyen detalles:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "El nombre es requerido",
    "field": "name"
  }
}

SDKs y Bibliotecas

Próximamente:

  • SDK JavaScript/TypeScript
  • SDK Python
  • SDK Go

Casos de Uso

Integración CI/CD

Actualizar automáticamente la arquitectura después de despliegues:

- name: Actualizar Arquitectura
  run: |
    curl -X POST \
      -H "X-API-Key: ${{ secrets.ARCHYL_API_KEY }}" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

Herramientas Personalizadas

Construir herramientas internas que interactúen con tu arquitectura:

  • Validación de arquitectura
  • Verificación de cumplimiento
  • Generación de documentación

Asistentes de IA

Usar MCP para permitir que los asistentes de IA entiendan y actualicen tu arquitectura:

  • Hacer preguntas sobre tu arquitectura
  • Crear elementos a través de lenguaje natural
  • Generar documentación automáticamente

Documentación de la API

La documentación interactiva completa de la API está disponible en:

https://api.archyl.com/docs

Esta documentación OpenAPI incluye:

  • Todos los endpoints disponibles
  • Esquemas de solicitud/respuesta
  • Funcionalidad de prueba
  • Ejemplos de autenticación

Próximos Pasos