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

# API 概览与认证

> 使用 Bearer API 密钥认证 REST API，了解权限范围、错误格式和分页机制。

REST API 让你无需使用仪表盘即可将检测发现、原始活动、主机状态和检测规则拉取到自己的工具中，并将审核决定推送回来。所有接口都位于你部署的仪表盘主机的 `/v1/` 路径下：

```text theme={null}
https://<your-dashboard-host>/v1/...
```

> [!NOTE]
>
> Webhook 以推送方式补充 API —— 如果你希望在新检测发现出现时收到通知而不是轮询，请参阅 [Webhooks](https://hilt.ai/docs/zh/api/webhooks.md)。

***

## 创建 API 密钥

API 密钥在仪表盘中创建：**设置 → 账户 → API 密钥 → 创建 API 密钥**。

1. 为密钥起一个描述性名称（例如 `SIEM integration`）。
2. 选择**权限范围**：
   * **只读** —— 可列出检测发现、事件、主机和检测规则。
   * **读写** —— 包含只读的全部能力，另可通过审核接口接受或拒绝检测发现。
3. 可选设置**有效期**（30 天、90 天、1 年或永不过期）。

密钥仅在创建时**显示一次**——请立即复制。密钥形如：

```text theme={null}
hilt_live_a1b2c3d4e5f6...
```

每个账户最多可持有 20 个活跃密钥，可随时在同一页面吊销任意密钥，并查看每个密钥的最近使用时间。被吊销或过期的密钥会在下一次请求时立即被拒绝。

## 使用密钥

在每个请求中以 Bearer 令牌形式发送密钥：

```bash theme={null}
curl https://<your-dashboard-host>/v1/findings \
  -H "Authorization: Bearer hilt_live_a1b2c3d4e5f6..."
```

没有有效密钥的请求会收到 `401 Unauthorized`。

## 权限范围

密钥继承创建者的主机和团队限制——它能看到和执行的内容永远不会超过该用户的仪表盘账户。如果你的账户仅限于特定团队的主机，API 只返回这些主机的数据；请求其他主机会返回 `403`（检测发现查询则返回 `404`）。

## 错误

所有错误共用同一格式：

```json theme={null}
{ "error": "human-readable message" }
```

| 状态码 | 含义 |
| - | - |
| `400` | 参数、游标或请求体无效 |
| `401` | API 密钥缺失、无效、已吊销或已过期 |
| `403` | 密钥缺少写权限，或主机超出你的权限范围 |
| `404` | 资源不存在（对检测发现而言也可能是超出权限范围） |
| `500` | 内部查询失败——可安全重试 |
| `503` | 后端数据存储暂时不可用 |

## 分页

可能返回大量数据的列表接口（`/v1/findings`、`/v1/events`）使用游标分页：

* 通过 `limit` 控制页大小（默认 50，最大 200）。
* 当还有更多结果时，响应包含 `next_cursor` 字符串；将其作为 `cursor=` 参数传回以获取下一页。
* 持续跟随 `next_cursor` 直到其为 `null`——判断结果是否取完请只看游标，而不是页大小。

查询参数中的时间戳使用 RFC 3339 格式（`2026-07-03T00:00:00Z`）；除特别说明外，响应体中的事件和检测发现时间为 Unix 纳秒。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.