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
• Ejecutar, dirigir y programar agentes gestionados

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 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

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

Agentes Gestionados

Estos endpoints te permiten iniciar, seguir y programar ejecuciones de agentes gestionadas desde tus propias herramientas. Las rutas son relativas a la URL base.

Perfiles y Skills

Ejecuciones

Para comentar una línea del diff del agente, añade un anchor al mensaje. side es new para una línea del archivo tal como está escrito u old para una línea eliminada, y changeSeq es el número de secuencia del evento file_change cuyo diff comentas:

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Reuse the existing retry helper here",
    "anchor": {"path": "internal/billing/client.go", "line": 42, "side": "new", "changeSeq": 17}
  }' \
  https://api.archyl.com/api/v1/agents/runs/{runId}/steer

Programaciones

Conectores MCP

Además de los códigos de Manejo de Errores, estos endpoints devuelven 409 cuando el estado de una ejecución no permite la acción o el gate de preflight la rechaza, 422 cuando el proveedor o el modelo de IA de tu organización no puede ejecutar agentes gestionados, y 429 cuando no queda ninguna plaza de concurrencia libre. Los esquemas de petición y respuesta están en la referencia OpenAPI.

Manejo de Errores

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

Las respuestas de error incluyen detalles:

{
  "error": true,
  "message": "instructions are required to continue a run"
}

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

• Autenticación - Guía detallada de autenticación
• Servidor MCP - Configurar integración con asistentes de IA