/api/v1。健康探针、Prometheus 指标、公开共享链接和少数兼容协议也会使用其他路径。
基础 URL
本地实例：[http].external_url 的值。
身份验证
受保护的端点在Authorization 请求头中接受 Bearer Token：
脚本和采集器请使用 API Token。登录 Token 会过期，并让使用它的发送端中断。接入 Token 的细节参见数据源。
身份验证会生成包含主体、当前组织或平台范围，以及实际生效权限的 IAM 上下文。请求所属的组织始终来自这个上下文，请求体无法选择其他组织。
公开与自验证路由
少数路由无法使用组织的 Bearer Token，它们会改为验证范围更窄的凭据或策略：- 登录、注册策略与密码重置；
GET /api/v1/healthz与顶层的/metrics；- 公开资源共享的交换与共享会话请求；
- 签名文件下载与公开头像；
- 推送型连接器端点，它们验证推送 Token。
授权
一个端点可能要求以下一个或多个条件：- 组织权限，例如
streams.query； - 平台权限，例如
sys.telemetry.read； - 对资源的所有权、与资源的关系，或跨组织授权。
GET /api/v1/iam/capabilities 返回当前主体实际生效的权限。不要根据角色名称或可见的菜单项推断访问能力。
请求
- 大多数请求体是 JSON，使用
Content-Type: application/json。 - 兼容类接入端点使用各自协议的载荷，例如 Protobuf、NDJSON 或 gzip 压缩的请求体。
- 超过 2 MiB 的接入请求体会被拒绝并返回
413。 - 以
_micros结尾的字段保存以微秒表示的 Unix 时间。原生遥测记录使用_timestamp，同样以微秒计。 - 路径中的 id 和数据流名称需要做 URL 编码。
响应与错误
成功的响应是 JSON，除非端点以流或文件的形式返回。错误响应包含状态码，以及带有机器可读的error 码和 message 的 JSON 响应体：
validation_failed 错误还会附带 issues 数组，每个无效字段一项。
请求体无法解析时，请求在到达端点之前就会失败，此时的响应是纯文本而不是 JSON：
每个响应都带有
X-Request-Id 与 X-Trace-Id 响应头。报告服务端故障时请同时提供这两个值。
分页
可能返回大量行的端点接受limit 与 cursor，这类响应包含 items 与 next_cursor。把 next_cursor 作为 cursor 传回即可读取下一页，为空时停止。其他列表端点会返回完整列表，具体见各端点页面。
查询与长耗时任务
查询族接口返回普通 JSON、以流的形式返回 NDJSON，并把耗时较长的查询作为异步搜索任务运行。规模过大的查询会返回202，并带有 job_id 与 monitor 路径。流式调用方需要处理部分数据到达的情况，并在不再需要结果时取消请求，参见查询。
生成的报告、Profile 数据块和导出文件等大体积产物，通过限定范围的下载 Token 以文件形式交付，而不是放在 JSON 响应体中。
浏览 API
API 目录
路由族、用途以及保护它们的权限。
身份验证
登录并管理 API Token。
数据接入
发送原生 JSON 与兼容协议的遥测数据。
查询
运行 SQL、兼容 PromQL、流式与已保存的查询。
APM
读取服务、事务、依赖与错误指标。
数据流
创建、查看并配置数据流。
告警
管理规则、事件、渠道与升级。
关联与 Web
搜索、拓扑、链路与跨信号跳转。
平台与管理
审计日志、加密密钥与健康检查。