API 概览

Forgexa 提供基于 FastAPI 构建的 RESTful API。

基础 URL

环境	URL
生产环境（Forgexa Cloud）	https://api.forgexa.net/api/v1
私有部署	http://<your-server>:8000/api/v1
本地开发	http://localhost:8000/api/v1

认证

除 /auth/login 和 /auth/register 外，所有 API 端点都需要认证，支持以下方式：

• JWT Bearer Token — 通过 /auth/login 获取，24 小时过期
• 个人访问令牌（PAT） — 通过 /users/me/api-tokens 创建，适用于 CI/CD 和脚本

# 登录（JWT）
curl -X POST https://api.forgexa.net/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "admin123"}'

# 响应: { "access_token": "eyJ...", "token_type": "bearer" }

# 使用 JWT 令牌
curl https://api.forgexa.net/api/v1/workspaces \
  -H "Authorization: Bearer eyJ..."

# 或使用 PAT
curl https://api.forgexa.net/api/v1/workspaces \
  -H "Authorization: Bearer pat_a1b2c3..."

交互式文档

FastAPI 在私有部署实例上提供交互式文档：

• Swagger UI：http://<your-server>:8000/docs
• ReDoc：http://<your-server>:8000/redoc

本地开发时访问 http://localhost:8000/docs。

API 分类

• 认证 — 登录、注册、令牌管理
• 组织 — 组织 CRUD、成员、预算、审计日志
• 组织邀请 — 邀请用户加入组织
• 组织集成 — 组织级集成配置
• 工作空间 — 工作空间 CRUD、成员、设置
• 项目 — 项目 CRUD
• 需求 — 需求管理 + AI 分析
• 执行 — 执行生命周期管理
• 角色 & 权限 — RBAC 和自定义角色
• API 令牌 — 个人访问令牌管理
• 管理面板 — 平台管理员统计和审计日志

通用响应格式

成功

{
  "id": "uuid",
  "name": "...",
  "status": "...",
  "created_at": "2026-01-01T00:00:00Z"
}

错误

{
  "detail": "Error message"
}

分页

大多数列表端点直接返回数组。审计日志等大数据集使用分页响应：

{
  "total": 150,
  "page": 1,
  "page_size": 20,
  "items": [...]
}

通过查询参数进行过滤（page、page_size、action、start_date 等）。