> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# API 使用指南

> 了解如何认证、获取所需 ID 以及调用 Alephant API

本指南涵盖调用 Alephant API 前常用的参数：身份验证令牌、工作区 ID、资源 ID、日期范围以及范围限定的分析筛选条件。

## 基础 URL

请使用 API 参考中适用于您环境的 API 主机。本指南中的示例使用：

```bash
https://alephant.io
```

## 身份验证

大多数工作区 API 同时需要 `Authorization` 请求头和 `X-Workspace-Id` 请求头。

```bash
Authorization: Bearer <token>
X-Workspace-Id: <workspace-id>
```

支持的令牌类型取决于路由：

| 令牌类型         | 最适用场景              | 说明                                                     |
| ------------ | ------------------ | ------------------------------------------------------ |
| 用户 JWT       | 仪表盘和第一方 UI 会话      | 通常通过登录流程获取。                                            |
| 个人访问令牌 (PAT) | 服务器到服务器的工作区自动化     | 使用 `Bearer pat_...`；路由范围可能需要 `read`、`write` 或 `admin`。 |
| 虚拟密钥         | 密钥范围内的控制台和 MCP 工作流 | 调用工作区 API 前，请使用控制台路由发现范围。                              |

`/api/v1/pats` 下的 PAT 管理路由仅支持 JWT。PAT 无法管理其他 PAT。

## 查找所需 ID

许多 API 需要来自工作区的 ID。请使用 SaaS API 列出资源，然后将返回的 ID 传给分析或管理 API。

| ID             | 获取方式                                                             | 用途                           |
| -------------- | ---------------------------------------------------------------- | ---------------------------- |
| `workspaceId`  | `GET /api/v1/workspaces`，或从虚拟密钥开始时使用 `GET /api/v1/cockpit/scope` | `X-Workspace-Id` 和大多数工作区 API |
| `agentId`      | `GET /api/v1/agents`                                             | 智能体分析和范围限定的用量筛选              |
| `memberId`     | `GET /api/v1/members`                                            | 成员分析和范围限定的用量筛选               |
| `departmentId` | `GET /api/v1/departments`                                        | 部门分析、预算和范围限定的用量筛选            |
| `masterKeyId`  | `GET /api/v1/master-keys`                                        | 主密钥分析和密钥管理                   |

如果您的集成只有虚拟密钥 (`vk-...`)，请先调用：

```bash
curl https://alephant.io/api/v1/cockpit/scope \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY"
```

响应可能包含 `workspace.id`、`virtual_key.id`，以及可选的绑定 `entity.id` 和 `entity.department_id`。对于工作区范围内的 API，请使用 `workspace.id` 作为 `X-Workspace-Id`。

## 跟踪网关请求

通过 Alephant 网关发送模型流量时，请附加智能体和运行上下文，以便日志和分析能正确地将请求分组。

| 请求头                   | 范围                    |
| --------------------- | --------------------- |
| `Alephant-Agent-Id`   | 来自 Alephant 的稳定智能体 ID |
| `Alephant-Run-Id`     | 单次任务执行                |
| `alephant-session-id` | 对话、工作流或作业分组           |
| `x-request-id`        | 单次网关请求                |

示例：

```bash
curl https://ai.alephant.io/v1/chat/completions \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Alephant-Agent-Id: agt_support_bot_8f3a" \
  -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \
  -H "alephant-session-id: sess_customer_123_support_20260609" \
  -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Summarize this ticket." }
    ]
  }'
```

请参阅 [智能体 ID 和运行 ID](/docs/overview/core-concepts/agent-i-ds-and-run-i-ds) 了解完整的使用模式。

## 日期范围

分析端点通常接受格式为 `YYYY-MM-DD` 的 `dateFrom` 和 `dateTo`。

```text
dateFrom=2026-05-01
dateTo=2026-05-09
```

对于 SaaS API 中的 `/api/v1/analytics/*` 路由：

* 如果发送 `dateFrom` 或 `dateTo` 中的任一个，请同时发送两者。
* 如果两者都省略，服务会在支持的情况下使用当前计费周期。
* `dateFrom` 不得晚于 `dateTo`。

一些较底层的分析 API 端点改用 `start` 和 `end`。混用参数名称前，请查看端点参考。

## 范围限定的分析筛选条件

`GET /api/v1/analytics/usage` 支持范围限定的用量序列。最多设置以下其中一个：

* `agentId`
* `memberId`
* `departmentId`

示例：某个智能体的用量。

```bash
curl "https://alephant.io/api/v1/analytics/usage?dateFrom=2026-05-01&dateTo=2026-05-09&agentId=$AGENT_ID" \
  -H "Authorization: Bearer $ALEPHANT_PAT" \
  -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"
```

如果发送多个范围，API 会返回错误请求。

## 常用调用

工作区分析概览：

```bash
curl "https://alephant.io/api/v1/analytics/overview?dateFrom=2026-05-01&dateTo=2026-05-09" \
  -H "Authorization: Bearer $ALEPHANT_PAT" \
  -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"
```

成本明细：

```bash
curl "https://alephant.io/api/v1/analytics/costs?dateFrom=2026-05-01&dateTo=2026-05-09" \
  -H "Authorization: Bearer $ALEPHANT_PAT" \
  -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"
```

用量历史：

```bash
curl "https://alephant.io/api/v1/analytics/usage-history?months=12" \
  -H "Authorization: Bearer $ALEPHANT_PAT" \
  -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"
```

## SaaS API 与分析 API

请使用 SaaS API (`/api/v1/...`) 处理产品工作流、工作区管理和面向仪表盘的分析。

请使用分析 API (`/v1/analytics/...`) 处理较底层的遥测和由采集器支持的分析。这些端点通常需要相同的工作区上下文，但其参数名称和响应结构可能更具采集器特性。

构建外部集成时，除非您明确需要采集器级别的分析端点，否则请从 SaaS API 开始。