API 概览

Archyl 提供了全面的 API，让您可以将架构文档集成到您的工作流程、工具和自动化流水线中。

API 端点

Archyl 提供两种 API 接口：

REST API

REST API 提供对所有 Archyl 功能的完整访问：

创建和管理项目
添加、更新和删除架构元素
管理关系
处理 ADR 和文档
导出图表

基础 URL：https://api.archyl.com/api/v1

MCP 服务器

模型上下文协议（MCP）服务器使 AI 助手能够与您的架构进行交互：

Claude Code、Claude Desktop
Cursor
VS Code 配合 Copilot
其他兼容 MCP 的工具

SSE 端点：https://api.archyl.com/sse HTTP 端点：https://api.archyl.com/mcp

身份认证

所有 API 请求都需要使用 API 密钥进行身份认证：

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

创建 API 密钥

前往您的个人资料 → API 密钥
点击"创建 API 密钥"
选择权限（只读或读写）
复制并安全存储您的密钥

密钥权限

权限	描述
读取	查看项目、元素和文档
写入	创建和修改项目、元素、关系

快速入门

列出您的项目

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

错误处理

API 错误返回标准 HTTP 状态码：

状态码	描述
400	错误请求 - 参数无效
401	未授权 - API 密钥无效或缺失
403	禁止访问 - 权限不足
404	未找到 - 资源不存在
500	服务器内部错误

错误响应包含详细信息：

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Name is required",
    "field": "name"
  }
}

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 助手集成

API 概览 - Archyl Docs