HTTP API (Beta)

codebuddy --serve --port 8080 --session-id my-session

curl http://127.0.0.1:8080/api/v1/health
# {"data":{"status":"ok","uptime":12.3,"platforms":["generic","wecom","wechat-kf"]}}

X-CodeBuddy-Request: 1

CODEBUDDY_CODE_CORS_ORIGINS=http://localhost:5173 codebuddy --serve

  Endpoint    http://127.0.0.1:8321
  Web UI      http://127.0.0.1:8321/?password=<生成的密码>

  Password    <生成的密码>
  Config      ~/.codebuddy/settings.json

codebuddy --serve --auth none
# 或
CODEBUDDY_GATEWAY_AUTH=none codebuddy --serve

# 1) Bearer Token（推荐，同时携带安全头）
curl -H "X-CodeBuddy-Request: 1" \\
     -H "Authorization: Bearer YOUR_PASSWORD" \\
     http://host:port/api/v1/sessions

# 2) X-Access-Token（与 Bearer 等价，对齐 E2B envd 的凭据头习惯）
curl -H "X-CodeBuddy-Request: 1" \\
     -H "X-Access-Token: YOUR_PASSWORD" \\
     http://host:port/api/v1/sessions

# 3) Cookie（浏览器登录后自动携带）
curl -H "X-CodeBuddy-Request: 1" \\
     -H "Cookie: gateway_session=<sha256(password)>" \\
     http://host:port/api/v1/sessions

// 成功
{
    "data": { ... }
}

// 错误
{
    "error": {
        "code": "AUTH_REQUIRED",      // 机器可读错误码
        "message": "Authentication required"  // 人类可读描述
    }
}

# 派发后台智能体
curl -H "X-CodeBuddy-Request: 1" \\
  -H "Authorization: Bearer $PASSWORD" \\
  -H 'Content-Type: application/json' \\
  -X POST http://127.0.0.1:8080/api/v1/jobs \\
  -d '{"prompt":"检查当前仓库的测试状态","cwd":"/repo/app"}'

# 订阅 job 列表变化
curl -N -H "X-CodeBuddy-Request: 1" \\
  -H "Authorization: Bearer $PASSWORD" \\
  http://127.0.0.1:8080/api/v1/jobs/events

-H "X-CodeBuddy-Request: 1" -H "Authorization: Bearer $PASSWORD"

curl http://127.0.0.1:8080/api/v1/health

# 发送消息（body 为 Gateway Protocol 格式，id/type 必填）
curl -X POST http://127.0.0.1:8080/api/v1/runs \\
  -H "Content-Type: application/json" \\
  -H "X-CodeBuddy-Request: 1" \\
  -d '{
    "id": "run-1",
    "type": "message",
    "source": {"platform": "generic", "sender": {"id": "dev", "name": "Developer"}, "conversation": {"id": "run-1", "type": "direct"}},
    "payload": {"text": "帮我分析代码性能"}
  }'

# 响应: {"data": {"runId": "uuid-xxx", "status": "accepted"}}

# 通过 SSE 流获取结果（同样需携带 X-CodeBuddy-Request 头）
curl -H "X-CodeBuddy-Request: 1" http://127.0.0.1:8080/api/v1/runs/uuid-xxx/stream

# 创建终端
curl -X POST http://127.0.0.1:8080/api/v1/pty \\
  -H "Content-Type: application/json" \\
  -d '{"cols": 120, "rows": 40}'

# 列出终端
curl http://127.0.0.1:8080/api/v1/pty

# SSE 流式获取输出（替代 WebSocket）
curl http://127.0.0.1:8080/api/v1/pty/SESSION_ID/output

# 发送输入
curl -X POST http://127.0.0.1:8080/api/v1/pty/SESSION_ID/input/send \\
  -H "Content-Type: application/json" \\
  -d '{"data": "ls -la\\n"}'

# 调整大小
curl -X POST http://127.0.0.1:8080/api/v1/pty/SESSION_ID/resize \\
  -H "Content-Type: application/json" \\
  -d '{"cols": 200, "rows": 50}'

# 销毁终端
curl -X DELETE http://127.0.0.1:8080/api/v1/pty/SESSION_ID

# 下载文件
curl "http://127.0.0.1:8080/api/v1/files/download?path=/tmp/test.txt"

# 上传文件
curl -X POST "http://127.0.0.1:8080/api/v1/files/upload?path=/tmp/upload.txt" \\
  -H "Content-Type: application/octet-stream" \\
  --data-binary @local-file.txt

# 获取文件信息
curl -X POST http://127.0.0.1:8080/api/v1/fs/stat \\
  -H "Content-Type: application/json" \\
  -d '{"path": "/tmp"}'

# 列出目录
curl -X POST http://127.0.0.1:8080/api/v1/fs/list \\
  -H "Content-Type: application/json" \\
  -d '{"path": "/tmp", "depth": 2}'

# 创建目录
curl -X POST http://127.0.0.1:8080/api/v1/fs/mkdir \\
  -H "Content-Type: application/json" \\
  -d '{"path": "/tmp/new-dir"}'

# 文件模糊搜索（CBC 增强）
curl "http://127.0.0.1:8080/api/v1/fs/search?query=component&limit=10"

# 启动进程（JSON 模式）
curl -X POST http://127.0.0.1:8080/api/v1/process/start \\
  -H "Content-Type: application/json" \\
  -d '{"process": {"cmd": "python3", "args": ["script.py"]}, "tag": "my-script"}'

# 启动进程（SSE 流式输出）
curl -X POST http://127.0.0.1:8080/api/v1/process/start \\
  -H "Content-Type: application/json" \\
  -H "Accept: text/event-stream" \\
  -d '{"process": {"cmd": "python3", "args": ["script.py"]}}'

# 列出运行中进程
curl http://127.0.0.1:8080/api/v1/process/list

# 发送 stdin
curl -X POST http://127.0.0.1:8080/api/v1/process/input/send \\
  -H "Content-Type: application/json" \\
  -d '{"process": {"pid": 12345}, "input": {"stdin": "hello\\n"}}'

# 发送信号（SIGTERM）
curl -X POST http://127.0.0.1:8080/api/v1/process/signal/send \\
  -H "Content-Type: application/json" \\
  -d '{"process": {"tag": "my-script"}, "signal": 15}'

# 系统指标 + 实例进程指标
curl http://127.0.0.1:8080/api/v1/metrics
# 响应: { data: { ts, cpuCount, cpuUsedPct, memTotalMib, memUsedMib, diskUsed, diskTotal, instances: [{ id, cwd, pid, rssMib, heapUsedMib, heapTotalMib, uptimeSeconds, ... }] } }

# 获取当前工作空间的会话列表
curl http://127.0.0.1:8080/api/v1/sessions

# 获取所有工作空间的会话列表
curl http://127.0.0.1:8080/api/v1/sessions?cwd=*

# 获取指定工作目录的会话列表
curl http://127.0.0.1:8080/api/v1/sessions?cwd=/path/to/workspace

# 获取指定项目的会话列表（按压缩工作目录名过滤）
curl http://127.0.0.1:8080/api/v1/sessions?cwd=*&projectId=workspace-hash

# 重命名会话
curl -X POST http://127.0.0.1:8080/api/v1/sessions/SESSION_ID/rename \\
  -H "Content-Type: application/json" \\
  -d '{"name": "性能优化讨论"}'

# 获取文件 diff（需要文件在 checkpoint 中被跟踪）
curl -X POST http://127.0.0.1:8080/internal/file-changes/diff \\
  -H "Content-Type: application/json" \\
  -d '{"path": "/path/to/file.ts"}'
# 响应: {"data": {"path": "/path/to/file.ts", "oldText": "...", "newText": "..."}}

# 列出可回退的 checkpoint
curl -X POST http://127.0.0.1:8080/internal/file-changes/checkpoints \\
  -H "Content-Type: application/json" \\
  -d '{}'
# 响应: {"data": {"checkpoints": [{"id": "xxx", "label": "...", "createdAt": 1234567890, "files": [...], "additions": 5, "deletions": 2}]}}

# 按文件撤回变更
curl -X POST http://127.0.0.1:8080/internal/file-changes/revert \\
  -H "Content-Type: application/json" \\
  -d '{"paths": ["/path/to/file.ts"]}'
# 响应: {"data": {"success": true, "revertedFiles": ["/path/to/file.ts"]}}

# 回退到指定 checkpoint
curl -X POST http://127.0.0.1:8080/internal/file-changes/revert \\
  -H "Content-Type: application/json" \\
  -d '{"checkpointId": "checkpoint-uuid", "scope": "CodeAndConversation"}'
# scope 可选值: "Code"（仅回退文件）, "Conversation"（仅回退对话）, "CodeAndConversation"（全部回退）

# 撤回全部变更（回退到最早的 checkpoint）
curl -X POST http://127.0.0.1:8080/internal/file-changes/revert \\
  -H "Content-Type: application/json" \\
  -d '{}'

# 列出已安装插件（每项带 isBuiltIn 布尔字段，标识是否属于内置市场）
curl http://127.0.0.1:8080/api/v1/plugins

# 只列出用户自行安装的插件，过滤掉内置市场下的插件
curl "http://127.0.0.1:8080/api/v1/plugins?includeBuiltin=false"

# 安装插件（"name@marketplace" 格式）
curl -X POST http://127.0.0.1:8080/api/v1/plugins \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# 启用插件
curl -X POST http://127.0.0.1:8080/api/v1/plugins/enable \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# 禁用插件
curl -X POST http://127.0.0.1:8080/api/v1/plugins/disable \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# 卸载插件
curl -X POST http://127.0.0.1:8080/api/v1/plugins/uninstall \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# 更新插件到最新版本（传 waitForApply=true 可等待重建生效后再返回）
curl -X POST http://127.0.0.1:8080/api/v1/plugins/update \\
  -H "Content-Type: application/json" \\
  -d '{"plugin": "my-plugin@my-marketplace"}'

# 列出插件市场（每项带 isBuiltIn 布尔字段）
curl http://127.0.0.1:8080/api/v1/plugins/marketplaces

# 只列出用户自行添加的市场，过滤掉内置市场
curl "http://127.0.0.1:8080/api/v1/plugins/marketplaces?includeBuiltin=false"

# 添加插件市场
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces \\
  -H "Content-Type: application/json" \\
  -d '{"source": "https://example.com/marketplace", "name": "my-marketplace"}'

# 添加插件市场并默认开启自动更新（等价于添加后再调一次 marketplaces/auto-update）
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces \\
  -H "Content-Type: application/json" \\
  -d '{"source": "https://example.com/marketplace", "name": "my-marketplace", "autoUpdate": true}'

# 浏览市场中的插件
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/browse \\
  -H "Content-Type: application/json" \\
  -d '{"marketplace": "my-marketplace"}'

# 更新市场（真正从远端拉取最新内容）
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/update \\
  -H "Content-Type: application/json" \\
  -d '{"marketplace": "my-marketplace"}'

# 开启/关闭市场自动更新（开启后后台周期性同步并升级已安装插件）
curl -X POST http://127.0.0.1:8080/api/v1/plugins/marketplaces/auto-update \\
  -H "Content-Type: application/json" \\
  -d '{"marketplace": "my-marketplace", "autoUpdate": true}'

# 删除插件市场
curl -X DELETE http://127.0.0.1:8080/api/v1/plugins/marketplaces/my-marketplace