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

# API Reference

> 面向开发者的 Manyfold API 速查，用于把 Agent 接入外部应用、脚本和 OpenAI 兼容 SDK。

Source: https://docs.manyfold.ai/zh/api-reference

## Token 与 scope

使用 nca_ API token。chat.completions scope 可以创建 chat turn，也可以读取同一用户通过 API 创建的会话；api.full 只建议给可信内部客户端使用。

## Endpoints

### POST /api/v1/chat/completions

创建 chat completion. 通过 OpenAI 兼容的 Chat Completions 形状向 Manyfold Agent 发起一个 turn。

Anchor: https://docs.manyfold.ai/zh/api-reference#chat-completions

Auth: Bearer API token，scope 为 chat.completions 或 api.full。
Quota: 计入每月 API request 配额。

| Parameter | Required | Description |
| --- | --- | --- |
| `model` | yes | Manyfold agent id，例如 agt_... |
| `messages` | yes | 支持 system/developer/user/assistant role；user 消息可包含 image_url 和 file 内容块。 |
| `stream` | no | 设为 true 时返回 Server-Sent Events。 |
| `metadata.session_id` | no | 继续此前 turn 返回的 Manyfold session。 |
| `stream_options.include_usage` | no | 设为 true 时，如果有用量数据，流式响应可包含最终 usage chunk。 |

Response:

- 非流式响应返回 chat.completion，可读取 choices[0].message.content。
- metadata.session_id 和 x-session-id 用于识别 Manyfold 会话。
- 流式响应发送 chat.completion.chunk event，最后是 data: [DONE]。

### GET /api/v1/conversations

列出会话. 列出通过 OpenAI 兼容 v1 API 创建的非渠道会话。

Anchor: https://docs.manyfold.ai/zh/api-reference#conversations

Auth: Bearer API token，scope 为 chat.completions 或 api.full。
Quota: 只读接口，不计入每月 API request 配额。

| Parameter | Required | Description |
| --- | --- | --- |
| `model` | no | 按 agent id 过滤。绑定到单个 agent 的 token 只能读取该 agent。 |
| `limit` | no | 1-100 条结果，默认 20。 |
| `after` | no | 使用上一页的 first_id 或 last_id 做 cursor pagination。 |
| `order` | no | 默认 desc；使用 asc 获取最旧优先。 |

Response:

- 返回 OpenAI 风格 list envelope，包含 object、data、first_id、last_id、has_more。
- 每个 item 包含 id、model、title、created_at、updated_at。

### GET /api/v1/conversations/{session_id}/messages

列出会话消息. 回放某个 API 会话里的消息，包含文本和完整 Manyfold content blocks。

Anchor: https://docs.manyfold.ai/zh/api-reference#conversation-messages

Auth: Bearer API token，scope 为 chat.completions 或 api.full。
Quota: 只读接口，不计入每月 API request 配额。

| Parameter | Required | Description |
| --- | --- | --- |
| `session_id` | yes | x-session-id 或 metadata.session_id 返回的 Manyfold session id。 |
| `limit` | no | 1-100 条结果，默认 20。 |
| `after` | no | 使用上一页的 first_id 或 last_id 做 cursor pagination。 |
| `order` | no | 默认 desc；使用 asc 按时间顺序回放。 |

Response:

- content 是 OpenAI 兼容的 message parts 数组。
- content_blocks 保留 Manyfold 特有的 transcript 细节，例如 tool call。