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

# 端点速查

> 全部 /v1/* 端点：路径、方法、鉴权与用途

# 端点速查

平台 API 挂在 `/v1` 前缀下。基地址：

```
https://api.profy.cn
```

这一页是全部端点的速查表。每个端点的完整请求与响应结构见对应的 API 详情页。

## 认证

除少数公开端点外，所有请求都要带 API Key：

```http theme={null}
Authorization: Bearer sk-pro-xxxxxxxx
```

多用户场景下还要标识终端用户：

```http theme={null}
X-End-User-Id: your-app-user-123
```

<Warning>
  `X-End-User-Id` 不是可选的装饰。用 API Key 调用 `/v1/chat/*`、`/v1/agents/run`、`/v1/sessions*`、`/v1/files*` 时**不带这个头会直接 400**，报错原文是：

  ```
  Missing required header: X-End-User-Id. Send a stable id for the terminal
  user this request acts on; it isolates their sessions, files and memory
  from other users of your API key.
  ```

  之所以宁可报错也不默认合并：一个 API Key 通常前置着很多终端用户，会话历史、沙箱文件、记忆都按这个头分区。缺了它就是所有人共用一个分区——串号的代价远高于多写一个 header。

  走 OAuth 的应用身份（有 app 上下文）豁免此校验，因为身份已经由授权流程确定。
</Warning>

## 全部端点

### 运行与会话

| 方法       | 路径                           | 用途                 |
| -------- | ---------------------------- | ------------------ |
| `POST`   | `/v1/agents/run`             | 单次运行专家（SSE 流式）     |
| `POST`   | `/v1/chat/completions`       | OpenAI 兼容的对话补全     |
| `POST`   | `/v1/sessions`               | 创建会话               |
| `GET`    | `/v1/sessions`               | 列出会话               |
| `GET`    | `/v1/sessions/:id`           | 获取会话详情             |
| `DELETE` | `/v1/sessions/:id`           | 删除会话               |
| `POST`   | `/v1/sessions/:id/adopt`     | 认领会话（把已有会话绑到当前调用方） |
| `GET`    | `/v1/sessions/:id/events`    | 订阅会话事件（SSE）        |
| `POST`   | `/v1/sessions/:id/events`    | 向会话发送事件（继续对话）      |
| `POST`   | `/v1/sessions/:id/interrupt` | 中断正在执行的会话          |

`agents/run` 与 `sessions/events` 底层是同一条执行流，区别只在有没有持久会话：

* 一次性任务用 `agents/run`，无状态
* 多轮对话用 `sessions`，服务端保留上下文

### 专家（Agents）

| 方法      | 路径                                       | 用途       |
| ------- | ---------------------------------------- | -------- |
| `POST`  | `/v1/agents`                             | 创建专家草稿   |
| `GET`   | `/v1/agents`                             | 列出你的专家   |
| `GET`   | `/v1/agents/:identifier`                 | 获取专家详情   |
| `PATCH` | `/v1/agents/:identifier`                 | 更新专家配置   |
| `POST`  | `/v1/agents/:identifier/publish`         | 提交发布审核   |
| `GET`   | `/v1/agents/:identifier/profile`         | 获取专家公开档案 |
| `GET`   | `/v1/agents/:identifier/opening-message` | 获取开场白    |

<Note>
  `publish` 是**提交审核**而不是直接上线。已上架专家发新版本时老版本保持在线，新版本进入待审队列——所以 publish 成功不代表用户看到的内容变了。用 `get_submission_status`（MCP）或专家详情里的待审字段确认状态。
</Note>

### 环境（沙箱模板）

| 方法       | 路径                     | 用途         |
| -------- | ---------------------- | ---------- |
| `POST`   | `/v1/environments`     | 创建可复用的沙箱环境 |
| `GET`    | `/v1/environments`     | 列出环境       |
| `GET`    | `/v1/environments/:id` | 获取环境详情     |
| `PATCH`  | `/v1/environments/:id` | 更新环境       |
| `DELETE` | `/v1/environments/:id` | 删除环境       |

### 文件

| 方法       | 路径                     | 用途       |
| -------- | ---------------------- | -------- |
| `POST`   | `/v1/files/upload-url` | 获取直传 URL |
| `POST`   | `/v1/files`            | 登记已上传的文件 |
| `DELETE` | `/v1/files/:id`        | 删除文件     |

上传是**两步式**：先拿直传 URL，把字节 PUT 到对象存储，再回来登记。这样大文件不经过 API 服务器，也不受请求体大小限制。

限额见 [限额表](/zh/documentation/reference/limits)。

### 用量与模型

| 方法     | 路径           | 鉴权             | 用途        |
| ------ | ------------ | -------------- | --------- |
| `GET`  | `/v1/meters` | **公开**         | 计量单位与费率结构 |
| `GET`  | `/v1/models` | 需鉴权            | 可用模型列表    |
| `POST` | `/v1/events` | 需 events scope | 上报自定义计量事件 |

`GET /v1/meters` 是全站唯一免鉴权的 `/v1` 端点——定价信息需要在用户登录前就能展示。

## OAuth 权限范围

第三方应用通过 OAuth 接入时按 scope 授权。

<Note>
  会话与环境的操作**复用 `agents:write` 而不是新造 `sessions:*` / `environments:*`**。原因是它们都是"以这个应用的身份操作这个应用的专家"，拆出新 scope 只会让授权页多两个用户看不懂的选项，却不带来任何真实的权限边界。
</Note>

## 请求示例

<CodeGroup>
  ```bash cURL theme={null}
  curl -N https://api.profy.cn/v1/agents/run \
    -H "Authorization: Bearer $PROFY_API_KEY" \
    -H "X-End-User-Id: user-123" \
    -H "Content-Type: application/json" \
    -d '{
      "agent": "my-expert",
      "message": "总结这份季度报告的三个关键结论"
    }'
  ```

  ```python Python theme={null}
  import os
  from profy import Profy

  async with Profy(
      api_key=os.environ["PROFY_API_KEY"],
      end_user_id="user-123",
  ) as client:
      async for event in client.agents.run_stream("my-expert", "总结这份季度报告"):
          if event.type == "output.text.delta":
              print(event.delta, end="", flush=True)
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.profy.cn/v1/agents/run", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PROFY_API_KEY}`,
      "X-End-User-Id": "user-123",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent: "my-expert",
      message: "总结这份季度报告的三个关键结论",
    }),
  });

  const reader = res.body!.getReader();
  // 逐块解析 SSE，事件类型见 SSE 事件页
  ```
</CodeGroup>

## 流式响应

`agents/run`、`chat/completions`、`sessions/:id/events` 都返回 `text/event-stream`。

事件名采用点号分层命名（对齐 OpenAI Responses API），完整词表见 [SSE 事件](/zh/developers/reference/sse-events)。

<Warning>
  流结束的标记是 `data: [DONE]`，它**不是**一个 JSON 事件，直接 `JSON.parse` 会抛异常。解析循环必须先判断这一行。
</Warning>

## 已知边界

| 事项                  | 状态                                                                       |
| ------------------- | ------------------------------------------------------------------------ |
| Webhook 事件回调        | **未上线**。文档里的 webhook 示例属于前瞻设计，当前不会收到回调                                   |
| Python SDK 版本       | 仓库内 `1.0.0`，PyPI 上是 `0.1.0`，存在版本漂移。以仓库源码为准                               |
| MCP `install_skill` | **是 stub**：返回成功但不真正安装。详见 [MCP Tools](/zh/developers/reference/mcp-tools) |

<Warning>
  这三条不写进文档的话，你会花几个小时排查"为什么 webhook 收不到"或"为什么技能装了没生效"，而根因是功能本身还没接线。宁可承认缺口，也不让你在不存在的东西上浪费时间。
</Warning>

## 相关页面

<CardGroup cols={2}>
  <Card title="SSE 事件" icon="bolt" href="/zh/developers/reference/sse-events">
    流式事件的完整词表
  </Card>

  <Card title="错误码" icon="triangle-exclamation" href="/zh/developers/error-codes">
    全部业务码与状态推导
  </Card>

  <Card title="认证" icon="key" href="/zh/developers/authentication">
    API Key 与 OAuth
  </Card>

  <Card title="环境变量" icon="sliders" href="/zh/developers/reference/environment-variables">
    SDK 与集成的配置项
  </Card>
</CardGroup>

<Note>
  核对日期 2026-08-11。来源：`services/core/src/routes/platform-api/`（`index.ts`、`agents.ts`、`sessions.ts`、`environments.ts`、`files.ts`）、`services/core/src/index.ts`（`/v1` 挂载点）。
</Note>