跳转到主要内容
MoleSignal 暴露单一带版本的 HTTP API（v1）。本页介绍适用于每个端点的通用约定。具体端点 —— 含请求/响应 schema 与在线调试台 —— 列在左侧边栏。

​
Base URL

所有端点都在 /api/v1 之下。沙箱里是： 
http://localhost:5080/api/v1
生产环境替换为你自己的域名（例如 https://molesignal.example.com/api/v1）。

​
认证

除特别说明外，每个端点都需要 bearer token： 
Authorization: Bearer <token>
token 可以是：
  • 从 POST /api/v1/auth/login 获取的 JWT，或
  • 形如 ms_<prefix>_<secret> 的 API token（见 安全）。
仅三个路由免认证：/api/v1/healthz、/api/v1/auth/login、/metrics。

​
请求

  • 请求体为 JSON（Content-Type: application/json），但模拟其他协议的接入端点除外 （Elasticsearch _bulk、Loki、Prometheus remote_write 使用各自的原生格式）。
  • 时间戳为微秒 —— Unix 纪元起算，接入记录（_timestamp）与查询时间范围 （time_range.start / time_range.end）都是。
  • 租户隔离：每个请求都限定在你的 org_id 下。服务端会把 org_id 谓词改写进每个查询计划， 数据不会跨组织。

​
成功响应

2xx 响应返回 JSON，具体结构因端点而异（各端点页单独说明）。例如查询端点返回： 
{
  "rows": [{ "level": "error", "count": 12 }],
  "columns": ["level", "count"],
  "scanned_rows": 10432,
  "took_ms": 18,
  "cache_hit": false
}
部分端点在你发送 Accept: application/x-ndjson 时以 NDJSON 流式返回；流式会绕过 query_result 缓存。

​
错误响应

错误返回统一的 JSON 信封，只含一个 error 字段： 
{
  "error": "invalid argument: time_range.start must be < end"
}

​
状态码

码含义
200成功
400参数非法
401未授权 —— token 缺失或无效
403禁止 —— 角色或 license 不足
404未找到，或跨组织查找
409冲突 —— 唯一约束或状态冲突
413配额耗尽（存储上限）
429限流（接入/查询 QPS 配额）

​
限流与配额

每个组织都有租户级配额：接入 QPS、查询 QPS、存储。超限返回 429（限流）或 413（存储）， 并附审计记录与告警。见 安全。

​
端点

端点在侧边栏中分组：

认证

数据接入

查询

流

告警

关联与 Web

管理

部分端点（SSO、clusters、connectors、copilot、RUM）位于付费/特性构建之后 —— 见 付费版端点。