API概要

Archylは、アーキテクチャドキュメントをワークフロー、ツール、自動化パイプラインに統合するための包括的なAPIを提供しています。

APIエンドポイント

Archylは2つのAPIインターフェースを提供しています:

REST API

REST APIはArchylの全機能へのフルアクセスを提供します:

• プロジェクトの作成と管理
• アーキテクチャ要素の追加、更新、削除
• リレーションシップの管理
• ADRとドキュメントの操作
• ダイアグラムのエクスポート
• マネージドエージェントの実行、指示、スケジュール設定

ベースURL: https://api.archyl.com/api/v1

MCPサーバー

Model Context Protocol（MCP）サーバーにより、AIアシスタントがアーキテクチャと対話できます:

• Claude Code、Claude Desktop
• Cursor
• VS Code（Copilot連携）
• その他のMCP対応ツール

HTTPエンドポイント: https://api.archyl.com/mcp

認証

すべてのAPIリクエストにはAPIキーによる認証が必要です:

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

APIキーの作成

1. プロフィール → APIキー に移動
2. 「APIキーを作成」をクリック
3. 権限を選択（読み取り専用または読み書き）
4. キーをコピーして安全に保管

キーの権限

クイックスタート

プロジェクト一覧の取得

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

システムの作成

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-commerce Platform",
    "description": "Main e-commerce system",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

リレーションシップの作成

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "system-1",
    "targetId": "system-2",
    "label": "Sends orders to",
    "technology": "REST/HTTPS"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/relationships

マネージドエージェント

これらのエンドポイントを使うと、マネージドエージェント実行を独自のツールから開始、追跡、スケジュールできます。パスはベースURLからの相対パスです。

プロファイルとスキル

実行

エージェントの差分の行にコメントするには、メッセージに anchor を追加します。side は書かれたとおりのファイルの行なら new、削除された行なら old で、changeSeq はコメント対象の差分を持つ file_change イベントのシーケンス番号です:

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

スケジュール

MCPコネクタ

これらのエンドポイントは、エラーハンドリングに記載のコードに加えて、実行の状態がその操作を許可しない場合やプリフライトゲートが拒否した場合に 409、組織の AI プロバイダーまたはモデルでマネージドエージェントを実行できない場合に 422、同時実行枠に空きがない場合に 429 を返します。リクエストとレスポンスのスキーマは OpenAPI リファレンスを参照してください。

エラーハンドリング

APIエラーは標準のHTTPステータスコードを返します:

エラーレスポンスには詳細が含まれます:

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

SDK・ライブラリ

近日公開予定:

• JavaScript/TypeScript SDK
• Python SDK
• Go SDK

ユースケース

CI/CD連携

デプロイ後にアーキテクチャを自動更新:

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

カスタムツール

アーキテクチャと対話する社内ツールの構築:

• アーキテクチャの検証
• コンプライアンスチェック
• ドキュメント生成

AIアシスタント

MCPを使用してAIアシスタントにアーキテクチャの理解と更新を任せる:

• アーキテクチャに関する質問
• 自然言語による要素の作成
• ドキュメントの自動生成

APIドキュメント

完全なインタラクティブAPIドキュメントは以下で利用可能です:

https://api.archyl.com/docs

このOpenAPIドキュメントには以下が含まれます:

• 利用可能な全エンドポイント
• リクエスト/レスポンススキーマ
• 試行機能
• 認証の例

次のステップ

• 認証 - 詳細な認証ガイド
• MCPサーバー - AIアシスタント連携のセットアップ