make-api-shell-connection-workflow
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMake API Shell + Connection Workflow
Make API Shell + 连接工作流
Use this skill for one specific workflow family:
- discover the correct Make app and app-specific API-call module
- reuse or build a reusable shell scenario with StartSubscenario, one app API-call module, and ReturnData
- reuse an existing suitable connection or create the connection request needed by that shell
- patch the shell with the selected connection once authorization is complete
- run the scenario and use it as a generic SaaS retrieval transport for email, CRM, tickets, and similar systems
This skill is primarily about provisioning and shell construction. Treat business retrieval as a second phase that starts only after the connection is ready and the shell has been validated against current workspace metadata.
The generic shell described here is an API transport wrapper, not business logic. It should behave like a reusable API endpoint for any SaaS app that Make can front, including email, CRM, ticketing, support, marketing, or task systems.
本技能适用于以下特定工作流类别:
- 发现正确的Make应用及应用专属API调用模块
- 复用或构建包含StartSubscenario、一个应用API调用模块和ReturnData的可复用shell场景
- 复用现有合适的连接,或创建该shell所需的连接申请
- 授权完成后,将选中的连接配置到shell中
- 运行场景,并将其用作电子邮件、CRM、工单及类似系统的通用SaaS检索传输工具
本技能主要聚焦于配置和shell构建。业务检索属于第二阶段,仅在连接就绪且shell已通过当前工作区元数据验证后才可启动。
本文所述的通用shell是一个API传输包装器,而非业务逻辑。它应表现为可复用的API端点,适用于Make可对接的任何SaaS应用,包括邮件、CRM、工单、支持、营销或任务系统。
Quick routing
快速导航
Read the file that matches the current task:
| Task | Reference |
|---|---|
| Discover the app, module, and connection type layers | Discovery and Shells |
| Create, inspect, or resolve a credential request | Connection Requests |
| Choose and execute the post-connection retrieval path | Retrieval Execution |
| Sanitize examples and prepare a public shareable version | Sanitization and Sharing |
| Start from a generic blueprint template | Example shell blueprint |
阅读与当前任务匹配的文件:
| 任务 | 参考文档 |
|---|---|
| 发现应用、模块和连接类型层级 | 发现与Shell |
| 创建、检查或处理凭证申请 | 连接申请 |
| 选择并执行连接后的检索路径 | 检索执行 |
| 清理示例并准备可公开分享的版本 | 清理与分享 |
| 从通用蓝图模板开始 | 示例shell蓝图 |
Fresh-agent operating sequence
新Agent操作流程
When a fresh agent gets a request such as "get my unread emails", "pull my open CRM leads", or "fetch my Jira tickets", the default operating sequence is:
- Resolve the provider anchor.
- email: Gmail vs Outlook vs other
- CRM: HubSpot vs Salesforce vs other
- ticketing: Jira vs Zendesk vs Linear vs other
- Resolve the target account, mailbox, workspace, project, or queue if the request is ambiguous.
- Resolve the active Make zone, organization, and team.
- Search the Make app catalog for the provider candidate using .
GET /api/v2/imt/apps?organizationId=ORG_ID&teamId=TEAM_ID&scoredSearch=true - Inspect the chosen app with and record the exact API-call module slug and both connection type layers.
GET /api/v2/imt/apps/{appName}/{version} - Reuse an existing suitable connection if one already matches the app, account identity, and required scope.
- Reuse an existing shell only when reusing an existing suitable connection. If a new connection must be created, create a new shell for that new connection instead of patching an old shell onto a newly authorized account.
- Only if no suitable connection exists, create a credential request.
- After the connection decision is settled, create or patch the shell according to the reuse rule above and verify that the shell can run.
- Run the narrowest possible retrieval request first through the API-call shell.
- Expand into list/search -> detail -> normalization only after the first shell run proves the path works.
The agent should not jump straight from "user wants SaaS data" to "create a new connection" or "call a direct SDK" without walking this sequence.
当新Agent收到诸如“获取我的未读邮件”“拉取我的未关闭CRM线索”或“获取我的Jira工单”等请求时,默认操作流程如下:
- 确定服务商锚点。
- 邮件:Gmail、Outlook或其他
- CRM:HubSpot、Salesforce或其他
- 工单:Jira、Zendesk、Linear或其他
- 若请求存在歧义,确定目标账户、邮箱、工作区、项目或队列。
- 确定当前活跃的Make区域、组织和团队。
- 使用在Make应用目录中搜索候选服务商。
GET /api/v2/imt/apps?organizationId=ORG_ID&teamId=TEAM_ID&scoredSearch=true - 使用检查选中的应用,并记录准确的API调用模块别名及两种连接类型层级。
GET /api/v2/imt/apps/{appName}/{version} - 若已有匹配应用、账户身份和所需权限范围的合适连接,则复用该连接。
- 仅当复用现有合适连接时,才可复用现有shell。若必须创建新连接,则为该新连接创建新shell,而非将旧shell配置到新授权的账户上。
- 仅当没有合适的现有连接时,才创建凭证申请。
- 连接决策确定后,根据上述复用规则创建或配置shell,并验证shell可正常运行。
- 首先通过API调用shell执行最精简的检索请求。
- 仅在首次shell运行验证路径可行后,再扩展为列表/搜索 -> 详情 -> 标准化流程。
Agent不应直接从“用户需要SaaS数据”跳转到“创建新连接”或“调用直接SDK”,必须遵循上述流程。
Input-resolution gates
输入确认关卡
Before provisioning or retrieval, explicitly resolve these inputs:
- provider anchor
- target account identity if multiple accounts or mailboxes are possible
- intended credential-request recipient if it may differ from the current token owner
- Make zone, organization, and team
If one of those items is missing and cannot be discovered safely, stop and ask only for that exact missing item.
在配置或检索之前,需明确确认以下输入:
- 服务商锚点
- 若存在多个账户或邮箱,需确定目标账户身份
- 若凭证申请接收方可能与当前令牌所有者不同,需确定接收方
- Make区域、组织和团队
若上述某一项缺失且无法安全自动发现,应暂停操作并仅询问该缺失项。
Core rules
核心规则
- Never guess the API-call module name. Discover it from current Make metadata.
- Treat example apps such as Gmail, Outlook, or HubSpot as illustrations, not as universal defaults.
- Keep the two type layers separate:
- scenario/module connection parameter type
- connection listing or credential request type
- Prefer reuse before creation:
- existing suitable connection before new credential request
- existing shell scenario only when reusing an existing suitable connection
- a newly authorized connection must get a newly created shell
- Do not route business retrieval to native Make search/list/get modules. For this workflow family, always retrieve through the Make app's API-call shell.
- Ask for confirmation before writing into an existing live scenario or replacing a connection mapping.
- Keep public examples sanitized. Do not include real names, user IDs, team IDs, organization IDs, tenant-specific hosts, or claims that a single private workspace proves a universal rule.
- Use a clean base URL variable in examples. For public examples, default to and keep placeholders generic. Do not mention
https://us1.make.comin public examples unless the current user explicitly provides or requests that zone. Valid zones can bewe.make.com,eu1,eu2,us1, orus2, and if the user provides a custom zone orwe, accept it.BASE_URL - Separate four phases explicitly:
- provider and app resolution
- connection provisioning
- shell provisioning
- retrieval execution and output normalization
- Do not assume the generic three-module blueprint is automatically activatable for every app. Before activation, compare the middle module metadata with a real current blueprint or module export for the same app and version in the active workspace.
- For the generic API shell contract that uses with ExpectDataAny, the final mapper must return the app module response body as
scenario-service:ReturnData.data: {{3.body}} - Never replace that shell-contract default with or
{{3}}just because the full bundle looks tempting. The shell is meant to return the API response body, not the entire Make module bundle.{{3.data}} - Still inspect a real execution bundle for validation, but use that to confirm that contains the intended payload or error object — not to redefine the generic shell contract.
body - Resolve the active workspace zone before any team-scoped call. and
GET /api/v2/users/mecan succeed on multiple zones, whileGET /api/v2/imt/apps/...or scenario endpoints on the wrong zone can fail withGET /api/v2/connections?teamId=....403 Permission denied - For the REST endpoint, filter with
/api/v2/connectionsortype=.... Do not assume query parameters such astype[]=...are honored just because an MCP tool usesaccountName=...terminology.accountName - Do not ask the user to paste raw OAuth secrets, API keys, or passwords into chat. Use a credential request whenever a new connection must be created.
- If the user request is ambiguous, resolve the concrete provider and account first; if it is already explicit, do not ask again.
- If the Module 2 request method is ,
PUT, orPATCH, warn explicitly before execution. Treat those methods as mutating live SaaS operations, not passive retrieval.DELETE - Do not assume is enough for scenario runs. After creating or updating an on-demand shell, explicitly set the scenario-level interface with
StartSubscenario.metadata.interfaceand verify it before the first run./api/v2/scenarios/{scenarioId}/interface - Treat as the standard execution path for this shell family. Pass the business payload under
/api/v2/scenarios/{scenarioId}/runwith keys that match the scenario interface exactly, and preferdatafor validation runs.responsive: true - Shell reuse is app-specific, not just provider-family-specific. A shell built around one app module should not be repointed to another app module just because both belong to the same vendor suite.
- 切勿猜测API调用模块名称,必须从当前Make元数据中发现。
- 将Gmail、Outlook或HubSpot等示例应用仅视为说明,而非通用默认值。
- 区分两种类型层级:
- 场景/模块连接参数类型
- 连接列表或凭证申请类型
- 优先复用而非创建:
- 优先复用现有合适连接,而非创建新凭证申请
- 仅当复用现有合适连接时,才可复用现有shell场景
- 新授权的连接必须搭配新创建的shell
- 请勿将业务检索路由到Make原生的搜索/列表/获取模块。对于本工作流类别,始终通过Make应用的API调用shell进行检索。
- 在修改现有活跃场景或替换连接映射之前,需请求用户确认。
- 公开示例需经过清理,不得包含真实姓名、用户ID、团队ID、组织ID、租户专属主机,或声称单个私有工作区可证明通用规则。
- 在示例中使用清晰的基础URL变量。公开示例默认使用,并使用通用占位符。除非用户明确提供或要求,否则不要在公开示例中提及
https://us1.make.com。有效区域包括we.make.com、eu1、eu2、us1或us2,若用户提供自定义区域或we,则予以接受。BASE_URL - 明确区分四个阶段:
- 服务商与应用确认
- 连接配置
- shell配置
- 检索执行与输出标准化
- 切勿假设通用三模块蓝图可自动适用于所有应用。激活前,需将中间模块元数据与活跃工作区中同一应用及版本的真实蓝图或模块导出进行对比。
- 对于使用且设置ExpectDataAny的通用API shell协议,最终映射器必须将应用模块响应体返回为
scenario-service:ReturnData。data: {{3.body}} - 切勿因完整数据包看似诱人,就将shell协议默认值替换为或
{{3}}。shell旨在返回API响应体,而非整个Make模块数据包。{{3.data}} - 仍需检查真实执行数据包以进行验证,但仅用于确认包含预期 payload 或错误对象——而非重新定义通用shell协议。
body - 在进行任何团队范围的调用之前,需确认活跃工作区区域。和
GET /api/v2/users/me可在多个区域成功执行,而在错误区域调用GET /api/v2/imt/apps/...或场景端点可能会返回GET /api/v2/connections?teamId=...错误。403 Permission denied - 对于REST 端点,使用
/api/v2/connections或type=...进行过滤。切勿仅因MCP工具使用type[]=...术语,就假设accountName等查询参数会被生效。accountName=... - 请勿要求用户在聊天中粘贴原始OAuth密钥、API密钥或密码。每当必须创建新连接时,使用凭证申请。
- 若用户请求存在歧义,先确认具体服务商和账户;若请求已明确,则无需再次询问。
- 若模块2的请求方法为、
PUT或PATCH,执行前需明确警告。将这些方法视为会修改SaaS数据的操作,而非被动检索。DELETE - 切勿假设足以支持场景运行。创建或更新按需shell后,需使用
StartSubscenario.metadata.interface明确设置场景级接口,并在首次运行前进行验证。/api/v2/scenarios/{scenarioId}/interface - 将视为本shell类别的标准执行路径。将业务payload放在
/api/v2/scenarios/{scenarioId}/run下,且键名需与场景接口完全匹配,验证运行优先使用data。responsive: true - shell复用是应用专属的,而非仅服务商类别专属。基于一个应用模块构建的shell不应被重新指向另一个应用模块,即使两者属于同一供应商套件。
App binding and connection-family matrix
应用绑定与连接类别矩阵
The shell pattern is generic, but each actual shell is bound to one discovered Make app module.
Do not treat “Google” or “Microsoft” as a single interchangeable connection family. In Make, app families often split by product surface.
Common examples:
| Business surface | Example API-call module | Scenario/module connection parameter type | Common connection listing or request type |
|---|---|---|---|
| Gmail | | | |
| Google Calendar / Sheets / Drive style apps | app-specific Google module discovered from metadata | commonly | commonly |
| Outlook / Microsoft mail | | | |
Rules that follow from this:
- Reuse a shell only when the discovered app, module slug, version, and connection family still match.
- Reuse a connection only when the account identity and scopes still fit the requested operation.
- If a new connection is authorized for a different account or connection family, create a new shell for it instead of silently repointing an old shell.
When in doubt, inspect the exact app metadata and existing connection detail instead of inferring compatibility from the vendor name.
shell模式是通用的,但每个实际shell都绑定到一个已发现的Make应用模块。
请勿将“Google”或“Microsoft”视为单一可互换的连接类别。在Make中,应用类别通常按产品领域划分。
常见示例:
| 业务领域 | 示例API调用模块 | 场景/模块连接参数类型 | 常见连接列表或申请类型 |
|---|---|---|---|
| Gmail | | | |
| Google日历/表格/云端硬盘类应用 | 从元数据中发现的Google专属模块 | 通常为 | 通常为 |
| Outlook/微软邮件 | | | |
由此衍生的规则:
- 仅当已发现的应用、模块别名、版本和连接类别仍匹配时,才可复用shell。
- 仅当账户身份和权限范围仍符合请求操作时,才可复用连接。
- 若为不同账户或连接类别授权了新连接,需为其创建新shell,而非静默重新指向旧shell。
如有疑问,检查准确的应用元数据和现有连接详情,而非仅从供应商名称推断兼容性。
Standard shell shape
标准shell结构
The reusable shell has exactly three modules:
scenario-service:StartSubscenario- one app-specific Make API-call module discovered from metadata
scenario-service:ReturnData
Expose these shell inputs through StartSubscenario:
pathmethodheaderbody
Use the discovered middle module as the only app-specific part of the shell.
可复用的shell包含恰好三个模块:
scenario-service:StartSubscenario- 一个从元数据中发现的应用专属Make API调用模块
scenario-service:ReturnData
通过StartSubscenario暴露以下shell输入:
pathmethodheaderbody
将已发现的中间模块作为shell中唯一的应用专属部分。
Generic shell contract
通用shell协议
This shell is a generic API endpoint wrapper.
It receives:
pathmethodheaderbody
It forwards those values into the app-specific Make API-call module.
Default retrieval should use . Treat , , and as write/destructive methods and require explicit user confirmation before running them.
GETPUTPATCHDELETEIt returns exactly one thing:
- the response body from the app-specific Make API-call module
Therefore the shell contract is:
json
{
"data": "{{3.body}}"
}That contract is generic across SaaS providers. It applies whether the middle module fronts Gmail, Outlook, HubSpot, Jira, or another provider-specific Make API-call module.
The shell should not try to return:
- the whole Make bundle
{{3}} - a guessed nested field such as
{{3.data}} - transport metadata mixed together with the body
The shell is transport only. Business interpretation happens later.
本shell是一个通用API端点包装器。
它接收:
pathmethodheaderbody
它将这些值转发到应用专属的Make API调用模块。
默认检索应使用方法。将、和视为写入/破坏性方法,执行前需获得用户明确确认。
GETPUTPATCHDELETE它仅返回一项内容:
- 应用专属Make API调用模块的响应体
因此,shell协议为:
json
{
"data": "{{3.body}}"
}该协议适用于所有SaaS服务商,无论中间模块对接的是Gmail、Outlook、HubSpot、Jira还是其他服务商专属的Make API调用模块。
shell不应尝试返回:
- 完整的Make数据包
{{3}} - 猜测的嵌套字段,如
{{3.data}} - 与响应体混合的传输元数据
shell仅作为传输工具,业务解析在后续阶段进行。
Two-phase operating model
两阶段操作模型
Phase A: provisioning
阶段A:配置
Complete these steps first:
- identify the provider and exact Make app
- discover the exact app version and module slug
- determine both connection type layers
- look for an existing suitable connection for the correct account identity and scope
- look for an existing shell scenario that already fits the contract for that existing connection
- create or resolve the credential request only if reuse failed
- create a new shell if a new connection was created, or patch an existing shell only when reusing an existing connection
- verify that the shell runs with the chosen connection
Deliverable at the end of Phase A:
- a connection-ready API-call shell scenario
先完成以下步骤:
- 确定服务商和准确的Make应用
- 发现准确的应用版本和模块别名
- 确定两种连接类型层级
- 查找符合正确账户身份和权限范围的现有合适连接
- 查找符合该现有连接协议的现有shell场景
- 仅当复用失败时,创建或处理凭证申请
- 若创建了新连接,则创建新shell;若复用现有连接,则仅配置现有shell
- 验证选中的连接可使shell正常运行
阶段A的交付成果:
- 已配置好连接的API调用shell场景
Phase B: retrieval
阶段B:检索
Only after Phase A succeeds:
- configure the retrieval call through the API-call shell
- run a narrow validation query or lookup
- inspect the real output bundle shape
- keep fixed as the generic shell contract and update only downstream normalization if needed
ReturnData - rerun and verify the user-facing payload
Do not treat a successful credential request as proof that the retrieval stage is already solved.
Important:
- the generic three-module API shell remains the only retrieval transport in this workflow family
- keep the shell contract fixed as
data: {{3.body}} - do not switch to native retrieval/search/list modules as a fallback or optimization
- if authorization fails because an existing connection is expired or invalid, do not try to re-auth that connection in place; go through the credential-request path and then create a new shell for the new connection
仅在阶段A成功后执行:
- 通过API调用shell配置检索请求
- 执行精简的验证查询或查找
- 检查真实输出数据包结构
- 保持ReturnData固定为通用shell协议,仅在需要时更新下游标准化流程
- 重新运行并验证面向用户的payload
切勿将凭证申请成功视为检索阶段已解决的证明。
重要提示:
- 通用三模块API shell仍是本工作流类别中唯一的检索传输工具
- 保持shell协议固定为
data: {{3.body}} - 请勿切换到原生检索/搜索/列表模块作为 fallback 或优化方案
- 若因现有连接过期或无效导致授权失败,请勿尝试原地重新授权;需通过凭证申请路径处理,然后为新连接创建新shell
Interface-and-run rule
接口与运行规则
For on-demand shells, treat interface provisioning as a separate deployment step:
- create or update the scenario blueprint
- explicitly set
/api/v2/scenarios/{scenarioId}/interface - verify the interface shape before the first run
- only then call
/api/v2/scenarios/{scenarioId}/run
Use a run payload shaped like:
json
{
"data": {
"path": "...",
"method": "GET",
"header": [],
"body": null
},
"responsive": true
}The key names under must match the scenario interface exactly. If the interface was never explicitly set, can reject the call even when the module itself contains interface metadata.
datarunStartSubscenario对于按需shell,将接口配置视为单独的部署步骤:
- 创建或更新场景蓝图
- 明确设置
/api/v2/scenarios/{scenarioId}/interface - 在首次运行前验证接口结构
- 仅在完成上述步骤后调用
/api/v2/scenarios/{scenarioId}/run
使用如下结构的运行payload:
json
{
"data": {
"path": "...",
"method": "GET",
"header": [],
"body": null
},
"responsive": true
}dataStartSubscenariorunBody-handling compatibility rule
请求体处理兼容规则
Keep the generic shell contract stable, but do not assume every provider module tolerates an empty or null body the same way.
Observed-safe pattern:
- write-capable shells can expose and map
body - read-heavy shells may need to omit the Module 2 mapper entirely when the provider module serializes empty payloads badly on
bodyorGETDELETE
If a provider-specific Make API-call module fails only when is present-but-empty, prefer one of these patterns:
body- a read shell without a mapper
body - a write shell with a mapper
body - two separate shells when the provider behavior differs between read and write paths
Do not change for this. This is a Module 2 request-shape compatibility issue, not a shell-output-contract issue.
ReturnData保持通用shell协议稳定,但切勿假设每个服务商模块对空请求体或null请求体的处理方式相同。
已验证安全的模式:
- 支持写入的shell可暴露并映射
body - 以读取为主的shell,当服务商模块在或
GET请求中对空payload序列化处理不佳时,可能需要完全省略模块2的DELETE映射body
若服务商专属的Make API调用模块仅在存在但为空时失败,优先选择以下模式之一:
body- 无映射的读取shell
body - 有映射的写入shell
body - 当服务商在读取和写入路径上行为不同时,使用两个独立的shell
请勿因此修改ReturnData。这是模块2请求结构的兼容性问题,而非shell输出协议问题。
Response behavior
响应规范
When using this skill:
- first summarize the discovered app, version, exact API-call module name, and both connection type layers
- explicitly state how the provider was resolved: user statement, existing Make artifacts, or Make app-catalog lookup
- explicitly say whether the shell is being reused or newly created
- explicitly say whether the connection is being reused or newly requested
- explicitly state which phase you are in: provisioning or retrieval
- when retrieval begins, state the API-call plan: list/search path, any follow-up detail paths, and normalization plan
- if a new connection was created, explicitly state that a new shell was created for it
- if the request started as a business ask such as email, CRM, or tickets, state the business target and the exact API path pattern you chose
- explicitly label any assumptions
- keep write-operation prompts brief and concrete
- if Module 2 is about to run a ,
PUT, orPATCH, stop and warn before executionDELETE - if activation fails or looks wrong, stop calling the flow complete and report the exact failing phase
ReturnData - if sharing publicly, rewrite examples with placeholders and neutral labels before finalizing
使用本技能时:
- 首先总结已发现的应用、版本、准确的API调用模块名称及两种连接类型层级
- 明确说明服务商的确定方式:用户声明、现有Make工件或Make应用目录查询
- 明确说明shell是复用还是新建
- 明确说明连接是复用还是新申请
- 明确说明当前所处阶段:配置或检索
- 检索开始时,说明API调用计划:列表/搜索路径、后续详情路径(如有)及标准化计划
- 若创建了新连接,明确说明已为其创建新shell
- 若请求最初是业务需求(如邮件、CRM或工单),说明业务目标及所选的准确API路径模式
- 明确标注所有假设
- 写入操作的提示需简洁具体
- 若模块2即将执行、
PUT或PATCH操作,需暂停并发出警告DELETE - 若激活失败或ReturnData结果异常,请勿宣告流程完成,需报告具体失败阶段
- 若公开分享,需先用占位符和中性标签重写示例后再定稿
Related skills
相关技能
- for broader scenario architecture beyond this shell pattern
make-scenario-building - for detailed module configuration, mapping, webhooks, keys, and data stores
make-module-configuring - for Make MCP connection methods, scopes, and timeout behavior
make-mcp-reference
- :适用于本shell模式之外更广泛的场景架构
make-scenario-building - :适用于模块配置、映射、webhook、密钥和数据存储的详细设置
make-module-configuring - :适用于Make MCP连接方法、权限范围和超时行为
make-mcp-reference