API 概览

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

API 端点

Archyl 提供两种 API 接口：

REST API

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

  • 创建和管理项目
  • 添加、更新和删除架构元素
  • 管理关系
  • 处理 ADR 和文档
  • 导出图表
  • 运行、引导和定时调度托管 Agent

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

MCP 服务器

模型上下文协议（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

托管 Agent

通过这些端点，您可以在自己的工具中启动、跟进和定时调度托管 Agent 运行。路径均相对于基础 URL。

配置文件与技能

方法 路径 描述
GET /agents/skills 列出配置文件可启用的内置技能
GET /agents/profiles 列出 Agent 配置文件（若没有，会自动创建默认配置文件）
POST /agents/profiles 创建配置文件
PUT /agents/profiles/{id} 更新配置文件
DELETE /agents/profiles/{id} 删除配置文件，并暂停使用它的定时任务

运行

方法 路径 描述
POST /projects/{projectId}/agents/runs 在项目上启动运行
GET /agents/runs 列出运行，可按 projectId、status 或 parentRunId 筛选，并用 page 和 pageSize 分页
GET /agents/runs/{id} 获取运行
GET /agents/runs/{id}/events 列出序号 since 之后的运行事件
POST /agents/runs/{id}/cancel 取消运行
POST /agents/runs/{id}/steer 向 Agent 发送消息，可锚定到其 diff 的某一行
POST /agents/runs/{id}/respond 批准或拒绝 Agent 的计划，或回答其提问
POST /agents/runs/{id}/approve 启动被预检关卡保留在 awaiting_approval 状态的运行
POST /agents/runs/{id}/continue 启动新的运行，在同一分支和 Pull Request 上继续已结束的运行

要评论 Agent diff 中的某一行，请在消息中添加 anchor。side 为 new 表示文件当前写入的行，为 old 表示已删除的行；changeSeq 是您所评论的 diff 对应的 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

定时任务

方法 路径 描述
GET /agents/schedules 列出定时任务，可按 projectId 筛选
POST /agents/schedules 创建定时任务（5 字段 cron 表达式，按 UTC 计算）
PUT /agents/schedules/{id} 更新定时任务
POST /agents/schedules/{id}/toggle 启用或停用定时任务
POST /agents/schedules/{id}/trigger 立即按定时任务启动一次运行
DELETE /agents/schedules/{id} 删除定时任务

MCP 连接器

方法 路径 描述
GET /agents/connectors 列出连接器
POST /agents/connectors 创建连接器
PUT /agents/connectors/{id} 更新连接器
POST /agents/connectors/{id}/toggle 启用或停用连接器
DELETE /agents/connectors/{id} 删除连接器
POST /agents/connectors/test 测试连接并列出服务器的工具

除错误处理中列出的状态码外，这些端点还会在运行的状态不允许该操作或预检关卡拒绝时返回 409，在组织的 AI 提供商或模型无法运行托管 Agent 时返回 422，在没有空闲并发名额时返回 429。请求和响应的 schema 请参阅 OpenAPI 参考文档。

错误处理

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

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

错误响应包含详细信息：

{
  "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 文档包括：

  • 所有可用端点
  • 请求/响应模式
  • 在线测试功能
  • 身份认证示例

后续步骤