API Reference — Manyfold

三分钟完成接入

使用托管 API origin，创建带 scope 的 token，然后发送 OpenAI 兼容请求；model 字段填写 Manyfold agent id。

Base URL: https://api.manyfold.ai/api/v1
认证: Authorization: Bearer
推荐 scope: chat.completions

创建或选择一个 Agent，并复制它的 agt_ id。
在 Settings -> API tokens 创建 API token。
调用 /chat/completions，并带上 Authorization: Bearer $MF_API_TOKEN。

Endpoints

公开 v1 API 保持很小：创建 Agent turn，列出 API 创建的会话，并回放消息。

POST /api/v1/chat/completions 通过 OpenAI 兼容的 Chat Completions 形状向 Manyfold Agent 发起一个 turn。 GET /api/v1/conversations 列出通过 OpenAI 兼容 v1 API 创建的非渠道会话。 GET /api/v1/conversations/{session_id}/messages 回放某个 API 会话里的消息，包含文本和完整 Manyfold content blocks。

POST /api/v1/chat/completions

创建 chat completion

通过 OpenAI 兼容的 Chat Completions 形状向 Manyfold Agent 发起一个 turn。

参数

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

响应

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

认证: Bearer API token，scope 为 chat.completions 或 api.full。

配额: 计入每月 API request 配额。

GET /api/v1/conversations

列出会话

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

参数

请求	必填	说明
model	可选	按 agent id 过滤。绑定到单个 agent 的 token 只能读取该 agent。
limit	可选	1-100 条结果，默认 20。
after	可选	使用上一页的 first_id 或 last_id 做 cursor pagination。
order	可选	默认 desc；使用 asc 获取最旧优先。

响应

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

认证: Bearer API token，scope 为 chat.completions 或 api.full。

配额: 只读接口，不计入每月 API request 配额。

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

列出会话消息

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

参数

请求	必填	说明
session_id	必填	x-session-id 或 metadata.session_id 返回的 Manyfold session id。
limit	可选	1-100 条结果，默认 20。
after	可选	使用上一页的 first_id 或 last_id 做 cursor pagination。
order	可选	默认 desc；使用 asc 按时间顺序回放。

响应

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

认证: Bearer API token，scope 为 chat.completions 或 api.full。

配额: 只读接口，不计入每月 API request 配额。

示例

创建非流式 turn

curl https://api.manyfold.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $MF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agt_your_agent_id",
    "messages": [
      { "role": "user", "content": "Summarize this repository." }
    ]
  }'

响应

{
    "object": "chat.completion",
    "model": "agt_your_agent_id",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "..."
            },
            "finish_reason": "stop"
        }
    ],
    "metadata": {
        "session_id": "cts_...",
        "assistant_message_id": "..."
    }
}

流式响应

设置 stream: true 后会返回 Server-Sent Events。响应里的 x-session-id header 表示 Manyfold session。

curl -N https://api.manyfold.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $MF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agt_your_agent_id",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [
      { "role": "user", "content": "Write a short release note." }
    ]
  }'

列出最近会话

curl "https://api.manyfold.ai/api/v1/conversations?limit=20" \
  -H "Authorization: Bearer $MF_API_TOKEN"

回放一个会话

curl "https://api.manyfold.ai/api/v1/conversations/cts_your_session_id/messages?order=asc" \
  -H "Authorization: Bearer $MF_API_TOKEN"

错误格式

错误使用 OpenAI 风格 envelope，方便兼容客户端统一处理认证和参数校验失败。

{
    "error": {
        "message": "API token does not have chat.completions scope",
        "type": "authentication_error",
        "code": "invalid_api_key"
    }
}

完整 Chat 指南 · Conversation 指南