API 总览与认证
Argus 对外有两类 API，认证方式不同、用途不同。分清它们是接入的第一步。
| 查询侧 API | 上报侧 API | |
|---|---|---|
| 用途 | 读数据（日志 / 崩溃 / 性能 / 反馈…） | 写数据（SDK 上报事件） |
| 认证 | 个人访问令牌（PAT）Authorization: Bearer | DSN + HMAC-SHA256 签名 |
| 调用方 | 脚本 / AI / 任意 HTTP 客户端 | 端上 / 后端 SDK |
| 入口 | OpenAPI / 查询 REST API | 上报端点参考 |
查询侧：PAT Bearer
查询数据用个人访问令牌（Personal Access Token，PAT）。在 Console → Settings → Access Tokens
（/settings/pat）创建，勾选所需 scope（如 mcp:read），令牌形如 argus_pat_xxx 且绑定到单一
项目——project_id 由令牌自动注入，调用方无法跨项目，天然隔离。
POST /v1/tools/log.search HTTP/1.1
Host: <your-argus-host>
Authorization: Bearer argus_pat_xxx
Content-Type: application/json
{ "query": "error", "limit": 20 }同一套查询能力也通过 MCP Server 暴露给 Claude / Cursor 等 AI 客户端。REST 端点与 schema 见 OpenAPI / 查询 REST API。
上报侧：DSN + HMAC
SDK 上报事件用数据源名称（DSN）+ HMAC 签名，保证来源可信与内容完整。DSN 形如
argus://<public_key>:<secret_key>@<host:port>/<project_id>，机制详见
DSN 与 HMAC 签名。绝大多数场景你不需要手写签名——用对应平台的
SDK 即可。端点清单见 上报端点参考。
secret_key 只用于服务端 / SDK 内部签名，切勿泄露到前端可见处。Web SDK 的 DSN 是公开可见的， 其 HMAC 由 SDK 在受控范围内处理——不要把后端 DSN 的 secret 放进浏览器代码。
统一约定
所有 API 遵循一致的工程契约（API 约定基线 ）：
- 错误响应：统一 JSON 结构
{ error: { code, message, request_id, details } }。客户端基于 机器可读的code分支，不要解析message文本。 - 请求追踪：每个响应回带
X-Request-Id，报障时提供此 id 即可定位。 - 配额与限流：
402表示额度耗尽（须升级 / 付费），429表示速率过快（Retry-After后重试）。 区别见 套餐、配额与计费。