API-Übersicht

Archyl bietet eine umfassende API, mit der Sie Architekturdokumentation in Ihre Workflows, Tools und Automatisierungspipelines integrieren können.

API-Endpunkte

Archyl bietet zwei API-Schnittstellen:

REST-API

Die REST-API bietet vollen Zugriff auf alle Archyl-Funktionen:

Projekte erstellen und verwalten
Architekturelemente hinzufügen, aktualisieren und löschen
Beziehungen verwalten
ADRs und Dokumentation handhaben
Diagramme exportieren
Verwaltete Agenten ausführen, steuern und planen

Basis-URL: https://api.archyl.com/api/v1

MCP-Server

Der Model Context Protocol (MCP) Server ermöglicht KI-Assistenten die Interaktion mit Ihrer Architektur:

Claude Code, Claude Desktop
Cursor
VS Code mit Copilot
Andere MCP-kompatible Tools

HTTP-Endpunkt: https://api.archyl.com/mcp

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mit einem API-Schlüssel:

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

API-Schlüssel Erstellen

Gehen Sie zu Ihrem Profil → API-Schlüssel
Klicken Sie auf "API-Schlüssel erstellen"
Wählen Sie Berechtigungen (nur lesen oder lesen-schreiben)
Kopieren und speichern Sie Ihren Schlüssel sicher

Schlüsselberechtigungen

Berechtigung	Beschreibung
Lesen	Projekte, Elemente und Dokumentation anzeigen
Schreiben	Projekte, Elemente, Beziehungen erstellen und ändern

Schnellstart

Ihre Projekte Auflisten

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

Ein System Erstellen

curl -X POST \
  -H "X-API-Key: ihr-api-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-Commerce-Plattform",
    "description": "Haupt-E-Commerce-System",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

Eine Beziehung Erstellen

curl -X POST \
  -H "X-API-Key: ihr-api-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "system-1",
    "targetId": "system-2",
    "label": "Sendet Bestellungen an",
    "technology": "REST/HTTPS"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/relationships

Verwaltete Agenten

Mit diesen Endpunkten starten, verfolgen und planen Sie verwaltete Agent-Runs aus Ihren eigenen Tools. Die Pfade sind relativ zur Basis-URL.

Profile und Skills

Methode	Pfad	Beschreibung
`GET`	`/agents/skills`	Die integrierten Skills auflisten, die ein Profil aktivieren kann
`GET`	`/agents/profiles`	Agentenprofile auflisten (gibt es keines, wird ein Standardprofil angelegt)
`POST`	`/agents/profiles`	Ein Profil erstellen
`PUT`	`/agents/profiles/{id}`	Ein Profil aktualisieren
`DELETE`	`/agents/profiles/{id}`	Ein Profil löschen und die Zeitpläne pausieren, die es verwenden

Runs

Methode	Pfad	Beschreibung
`POST`	`/projects/{projectId}/agents/runs`	Einen Run in einem Projekt starten
`GET`	`/agents/runs`	Runs auflisten, gefiltert nach `projectId`, `status` oder `parentRunId` und paginiert mit `page` und `pageSize`
`GET`	`/agents/runs/{id}`	Einen Run abrufen
`GET`	`/agents/runs/{id}/events`	Die Ereignisse des Runs nach der Sequenznummer `since` auflisten
`POST`	`/agents/runs/{id}/cancel`	Einen Run abbrechen
`POST`	`/agents/runs/{id}/steer`	Dem Agenten eine Nachricht senden, optional an einer Zeile seines Diffs verankert
`POST`	`/agents/runs/{id}/respond`	Den Plan des Agenten freigeben oder ablehnen oder seine Frage beantworten
`POST`	`/agents/runs/{id}/approve`	Einen Run starten, den das Preflight-Gate im Status `awaiting_approval` zurückhält
`POST`	`/agents/runs/{id}/continue`	Einen neuen Run starten, der einen beendeten Run auf demselben Branch und Pull Request fortsetzt

Um eine Zeile im Diff des Agenten zu kommentieren, fügen Sie der Nachricht einen anchor hinzu. side ist new für eine Zeile der Datei in ihrer geschriebenen Fassung oder old für eine entfernte Zeile, und changeSeq ist die Sequenznummer des file_change-Events, dessen Diff Sie kommentieren:

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

Zeitpläne

Methode	Pfad	Beschreibung
`GET`	`/agents/schedules`	Zeitpläne auflisten, optional gefiltert nach `projectId`
`POST`	`/agents/schedules`	Einen Zeitplan erstellen (Cron-Ausdruck mit 5 Feldern, ausgewertet in UTC)
`PUT`	`/agents/schedules/{id}`	Einen Zeitplan aktualisieren
`POST`	`/agents/schedules/{id}/toggle`	Einen Zeitplan aktivieren oder deaktivieren
`POST`	`/agents/schedules/{id}/trigger`	Sofort einen Run aus dem Zeitplan starten
`DELETE`	`/agents/schedules/{id}`	Einen Zeitplan löschen

MCP-Konnektoren

Methode	Pfad	Beschreibung
`GET`	`/agents/connectors`	Konnektoren auflisten
`POST`	`/agents/connectors`	Einen Konnektor erstellen
`PUT`	`/agents/connectors/{id}`	Einen Konnektor aktualisieren
`POST`	`/agents/connectors/{id}/toggle`	Einen Konnektor aktivieren oder deaktivieren
`DELETE`	`/agents/connectors/{id}`	Einen Konnektor löschen
`POST`	`/agents/connectors/test`	Eine Verbindung testen und die Tools des Servers auflisten

Zusätzlich zu den Codes unter Fehlerbehandlung geben diese Endpunkte 409 zurück, wenn der Status eines Runs die Aktion nicht zulässt oder das Preflight-Gate ihn ablehnt, 422, wenn der KI-Anbieter oder das Modell Ihrer Organisation keine verwalteten Agenten ausführen kann, und 429, wenn kein Slot für gleichzeitige Runs frei ist. Request- und Response-Schemas finden Sie in der OpenAPI-Referenz.

Fehlerbehandlung

API-Fehler geben Standard-HTTP-Statuscodes zurück:

Code	Beschreibung
400	Ungültige Anfrage - Ungültige Parameter
401	Nicht autorisiert - Ungültiger oder fehlender API-Schlüssel
403	Verboten - Unzureichende Berechtigungen
404	Nicht gefunden - Ressource existiert nicht
500	Interner Serverfehler

Fehlerantworten enthalten Details:

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

SDKs & Bibliotheken

Demnächst verfügbar:

JavaScript/TypeScript SDK
Python SDK
Go SDK

Anwendungsfälle

CI/CD-Integration

Architektur nach Deployments automatisch aktualisieren:

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

Benutzerdefinierte Tools

Interne Tools erstellen, die mit Ihrer Architektur interagieren:

Architekturvalidierung
Compliance-Prüfung
Dokumentationsgenerierung

KI-Assistenten

MCP verwenden, um KI-Assistenten Ihre Architektur verstehen und aktualisieren zu lassen:

Fragen zu Ihrer Architektur stellen
Elemente durch natürliche Sprache erstellen
Dokumentation automatisch generieren

API-Dokumentation

Die vollständige interaktive API-Dokumentation ist verfügbar unter:

https://api.archyl.com/docs

Diese OpenAPI-Dokumentation enthält:

Alle verfügbaren Endpunkte
Request/Response-Schemas
Ausprobier-Funktionalität
Authentifizierungsbeispiele

Nächste Schritte

Authentifizierung - Detaillierte Authentifizierungsanleitung
MCP-Server - KI-Assistenten-Integration einrichten