API 触发器

概述

API 触发器将您的工作流公开为一个安全的 HTTP 端点。将 JSON 数据发送到该端点，您的工作流会立即处理它。API 调用始终针对您的最新部署执行。

配置输入格式

为每个参数添加一个 输入格式 字段。运行时输出键会镜像该模式，并且也可以在 <api.input> 下使用。

在编辑器中手动运行使用 value 列，因此您可以在不发送请求的情况下进行测试。在执行过程中，解析器会填充 <api.userId> 和 <api.input.userId>。

请求示例

curl -X POST \
  https://mandala.ayantram.com/api/workflows/WORKFLOW_ID/execute \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  -d '{"userId":"demo-user","maxTokens":1024}'

成功的响应会返回来自执行器的序列化执行结果。错误会显示验证、认证或工作流失败的信息。

流式响应

启用实时流式传输以在生成时逐字符接收工作流输出。这对于向用户逐步显示 AI 响应非常有用。

请求参数

添加以下参数以启用流式传输：

stream - 设置为 true 以启用服务器发送事件 (SSE) 流式传输
selectedOutputs - 要流式传输的块输出数组（例如，["agent1.content"]）

块输出格式

使用 blockName.attribute 格式指定要流式传输的块输出：

格式："blockName.attribute"（例如，如果您想流式传输 Agent 1 块的内容，可以使用 "agent1.content"）
块名称不区分大小写，空格会被忽略

示例请求

curl -X POST \
  https://mandala.ayantram.com/api/workflows/WORKFLOW_ID/execute \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  -d '{
    "message": "Count to five",
    "stream": true,
    "selectedOutputs": ["agent1.content"]
  }'

响应格式

流式响应使用服务器发送事件 (SSE) 格式：

data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":"One"}

data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", two"}

data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", three"}

data: {"event":"done","success":true,"output":{},"metadata":{"duration":610}}

data: [DONE]

每个事件包括：

流式块：{"blockId": "...", "chunk": "text"} - 实时生成的文本
最终事件：{"event": "done", ...} - 执行元数据和完整结果
终止符：[DONE] - 表示流结束

多块流式传输

当 selectedOutputs 包含多个块时，每个块会指示其来源：

curl -X POST \
  https://mandala.ayantram.com/api/workflows/WORKFLOW_ID/execute \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  -d '{
    "message": "Process this request",
    "stream": true,
    "selectedOutputs": ["agent1.content", "agent2.content"]
  }'

每个块中的 blockId 字段可让您将输出路由到正确的 UI 元素：

data: {"blockId":"agent1-uuid","chunk":"Processing..."}

data: {"blockId":"agent2-uuid","chunk":"Analyzing..."}

data: {"blockId":"agent1-uuid","chunk":" complete"}

输出参考

参考	描述
`<api.field>`	输入格式中定义的字段
`<api.input>`	整个结构化请求体

如果未定义输入格式，执行器仅在 <api.input> 处暴露原始 JSON。

一个工作流只能包含一个 API 触发器。更改后发布新部署，以确保端点保持最新。

文件上传格式

API 接受两种格式的文件：

1. Base64 编码文件（推荐用于 SDK）：

{
  "documents": [{
    "type": "file",
    "data": "data:application/pdf;base64,JVBERi0xLjQK...",
    "name": "document.pdf",
    "mime": "application/pdf"
  }]
}

单个文件的最大大小：20MB
文件会上传到云存储，并转换为具有所有属性的 UserFile 对象

2. 直接 URL 引用：

{
  "documents": [{
    "type": "url",
    "data": "https://example.com/document.pdf",
    "name": "document.pdf",
    "mime": "application/pdf"
  }]
}

文件不会上传，URL 会直接传递
适用于引用现有文件

文件属性

对于文件，可以访问所有属性：

属性	描述	类型
`<api.fieldName[0].url>`	签名下载 URL	string
`<api.fieldName[0].name>`	原始文件名	string
`<api.fieldName[0].size>`	文件大小（字节）	number
`<api.fieldName[0].type>`	MIME 类型	string
`<api.fieldName[0].uploadedAt>`	上传时间戳（ISO 8601）	string
`<api.fieldName[0].expiresAt>`	URL 过期时间戳（ISO 8601）	string

对于 URL 引用的文件，除了 uploadedAt 和 expiresAt 外，其他属性均可用，因为文件未上传到我们的存储中。

如果未定义输入格式，执行器将仅在 <api.input> 处暴露原始 JSON。

一个工作流只能包含一个 API 触发器。更改后发布新的部署，以确保端点保持最新。

API 触发器

On this page