> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 入门

> 基础 URL、身份验证、权限、请求约定、流式响应与错误处理。

MoleSignal 提供带版本的 HTTP API。产品端点通常使用 `/api/v1`；探针、Prometheus 指标、公开共享链接和部分兼容协议也会使用顶层路径。

## 基础 URL

本地实例：

```text theme={null}
http://localhost:5080/api/v1
```

生产环境请将主机替换为部署配置的外部可访问 URL。

## Bearer 身份验证

受保护端点接受登录 JWT 或 API Token：

```http theme={null}
Authorization: Bearer <token>
```

API Token 格式为 `ms_<prefix>_<secret>`。身份验证会生成包含主体、当前组织或平台范围，以及实际生效权限的 IAM 上下文。

## 公开与自验证路由

无法使用普通组织 Bearer Token 的路由会验证路由专用的窄范围凭据或策略。目前包括：

* 登录、注册策略与密码重置；
* 健康状态与 Prometheus 指标；
* 公开资源共享交换与共享会话请求；
* 签名文件下载与公开头像；
* Stripe 与推送型 Connector Webhook。

不要把公开路由理解为无限制访问。对应 Handler 会验证注册策略、共享 Token、下载 Token、签名或 Connector 凭据。

## 授权

受保护端点可以同时要求：

* `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 错误消息。常见状态包括：

| 状态    | 含义                            |
| ----- | ----------------------------- |
| `400` | 请求无效或参数不受支持。                  |
| `401` | 凭据缺失、无效、过期或未通过路由专用验证。         |
| `402` | 组织服务因计费或试用策略暂停。               |
| `403` | 缺少权限、资源关系、作用域或许可证功能。          |
| `404` | 资源不存在，或在已授权范围中不可见。            |
| `409` | 状态或唯一性冲突。                     |
| `413` | 负载或存储超过限制。                    |
| `429` | 超过限流。                         |
| `500` | 内部失败；使用请求 ID 与 Trace ID 进行关联。 |

响应可以包含 `X-Request-Id` 与 `X-Trace-Id`。报告服务端失败时请附上这些值。

## 浏览 API

<CardGroup cols={2}>
  <Card title="当前 API 目录" icon="list" href="/zh-Hans/api/catalog">
    将路由家族映射到产品能力与授权。
  </Card>

  <Card title="身份验证示例" icon="key" href="/zh-Hans/api/auth/login">
    登录并管理 API Token。
  </Card>

  <Card title="采集示例" icon="inbox" href="/zh-Hans/api/intake/native-json">
    发送原生 JSON 与协议兼容遥测。
  </Card>

  <Card title="查询示例" icon="magnifying-glass" href="/zh-Hans/api/query/execute">
    运行 SQL、兼容 PromQL、流式与保存查询。
  </Card>

  <Card title="告警示例" icon="bell" href="/zh-Hans/api/alerting/list-rules">
    管理规则、事件、渠道与升级。
  </Card>

  <Card title="Enterprise 能力" icon="key" href="/zh-Hans/api/admin/paid-edition">
    了解功能授权与受保护的系统许可证 API。
  </Card>
</CardGroup>