/api/v1；探针、Prometheus 指标、公开共享链接和部分兼容协议也会使用顶层路径。
基础 URL
本地实例：Bearer 身份验证
受保护端点接受登录 JWT 或 API Token：ms_<prefix>_<secret>。身份验证会生成包含主体、当前组织或平台范围，以及实际生效权限的 IAM 上下文。
公开与自验证路由
无法使用普通组织 Bearer Token 的路由会验证路由专用的窄范围凭据或策略。目前包括：- 登录、注册策略与密码重置；
- 健康状态与 Prometheus 指标；
- 公开资源共享交换与共享会话请求；
- 签名文件下载与公开头像；
- Stripe 与推送型 Connector Webhook。
授权
受保护端点可以同时要求：streams.query等组织权限；sys.licenses.read等平台权限；agent等功能授权；- 所有权、资源关系或跨组织授权；
- 活动组织或有效计费状态。
GET /api/v1/iam/capabilities 检查当前主体的实际生效快照。不要根据角色名称或隐藏导航项推断访问权。
请求
- 大多数请求体使用 JSON 与
Content-Type: application/json。 - 兼容采集端点使用各自原生负载，包括 Protobuf、NDJSON 或压缩请求体。
- 以
_micros结尾的字段使用 Unix 微秒时间。 - 原生遥测记录使用
_timestamp；转换 SDK 时间时请遵循具体端点结构。 - 将路径 ID 或数据流名称插入 URL 时必须进行 URL 编码。
- 组织范围来自已通过身份验证的 IAM 上下文，而不是模型或浏览器提供的组织 ID。
查询与长时间响应
查询家族支持普通 JSON、NDJSON 流式响应、运行中查询控制与异步搜索任务。流式调用方应处理网络分段交付与客户端取消。 大型 Agent 证据、生成报告、性能剖析文件与导出内容可以保存为文件，并通过限定范围 Token 下载，而不是嵌入 JSON。错误
API 错误使用 HTTP 状态码与 JSON 错误消息。常见状态包括：
响应可以包含
X-Request-Id 与 X-Trace-Id。报告服务端失败时请附上这些值。
浏览 API
当前 API 目录
将路由家族映射到产品能力与授权。
身份验证示例
登录并管理 API Token。
采集示例
发送原生 JSON 与协议兼容遥测。
查询示例
运行 SQL、兼容 PromQL、流式与保存查询。
告警示例
管理规则、事件、渠道与升级。
Enterprise 能力
了解功能授权与受保护的系统许可证 API。