Vue d'ensemble de l'API

Archyl fournit une API complète qui vous permet d'intégrer la documentation d'architecture dans vos workflows, outils et pipelines d'automatisation.

Points de terminaison API

Archyl offre deux interfaces API :

API REST

L'API REST fournit un accès complet à toutes les fonctionnalités d'Archyl :

• Créer et gérer des projets
• Ajouter, mettre à jour et supprimer des éléments d'architecture
• Gérer les relations
• Gérer les ADRs et la documentation
• Exporter les diagrammes
• Lancer, orienter et planifier des agents gérés

URL de base : https://api.archyl.com/api/v1

Serveur MCP

Le serveur Model Context Protocol (MCP) permet aux assistants IA d'interagir avec votre architecture :

• Claude Code, Claude Desktop
• Cursor
• VS Code avec Copilot
• Autres outils compatibles MCP

Point de terminaison HTTP : https://api.archyl.com/mcp

Authentification

Toutes les requêtes API nécessitent une authentification via une clé API :

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

Créer des Clés API

1. Allez dans votre Profil → Clés API
2. Cliquez sur "Créer une Clé API"
3. Choisissez les permissions (lecture seule ou lecture-écriture)
4. Copiez et stockez votre clé en sécurité

Permissions des Clés

Démarrage Rapide

Lister Vos Projets

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

Créer un Système

curl -X POST \
  -H "X-API-Key: votre-cle-api" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plateforme E-commerce",
    "description": "Système e-commerce principal",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

Créer une Relation

curl -X POST \
  -H "X-API-Key: votre-cle-api" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "system-1",
    "targetId": "system-2",
    "label": "Envoie les commandes à",
    "technology": "REST/HTTPS"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/relationships

Agents Gérés

Ces points de terminaison vous permettent de lancer, suivre et planifier des exécutions d'agents gérées depuis vos propres outils. Les chemins sont relatifs à l'URL de base.

Profils et Skills

Exécutions

Pour commenter une ligne du diff de l'agent, ajoutez un anchor au message. side vaut new pour une ligne du fichier tel qu'il est écrit ou old pour une ligne supprimée, et changeSeq est le numéro de séquence de l'événement file_change dont vous commentez le diff :

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

Planifications

Connecteurs MCP

En plus des codes décrits dans Gestion des Erreurs, ces points de terminaison renvoient 409 quand l'état d'une exécution ne permet pas l'action ou que le gate de preflight la refuse, 422 quand le fournisseur ou le modèle d'IA de votre organisation ne peut pas faire tourner d'agents gérés, et 429 quand aucune place d'exécution simultanée n'est libre. Les schémas de requête et de réponse se trouvent dans la référence OpenAPI.

Gestion des Erreurs

Les erreurs API retournent des codes de statut HTTP standards :

Les réponses d'erreur incluent des détails :

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

SDKs & Bibliothèques

À venir :

• SDK JavaScript/TypeScript
• SDK Python
• SDK Go

Cas d'Utilisation

Intégration CI/CD

Mettre à jour automatiquement l'architecture après les déploiements :

- name: Mettre à jour l'Architecture
  run: |
    curl -X POST \
      -H "X-API-Key: ${{ secrets.ARCHYL_API_KEY }}" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

Outillage Personnalisé

Construire des outils internes qui interagissent avec votre architecture :

• Validation d'architecture
• Vérification de conformité
• Génération de documentation

Assistants IA

Utiliser MCP pour permettre aux assistants IA de comprendre et mettre à jour votre architecture :

• Poser des questions sur votre architecture
• Créer des éléments en langage naturel
• Générer automatiquement de la documentation

Documentation API

La documentation API interactive complète est disponible à :

https://api.archyl.com/docs

Cette documentation OpenAPI inclut :

• Tous les points de terminaison disponibles
• Schémas de requête/réponse
• Fonctionnalité d'essai
• Exemples d'authentification

Prochaines Étapes

• Authentification - Guide détaillé d'authentification
• Serveur MCP - Configurer l'intégration avec les assistants IA