pipefy-api-fallback

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pipefy API Fallback (Tier 3 — Last Resort)

Pipefy API 备用方案（第3层——最后手段）

This skill activates only after Tiers 1 and 2 have failed. Call the Pipefy GraphQL API directly, bypassing the MCP server.

此技能仅在第1层和第2层方案失效后启用。绕过MCP服务器，直接调用Pipefy GraphQL API。

3-tier resolution strategy (always follow in order)

三层解决策略（务必按顺序执行）

Tier	Method	When
1	Dedicated MCP tool ( `create_card` , `get_phase_cards` , `get_phase_allowed_move_targets` , `update_pipe` , etc.)	Always try first. For card/phase seeding and inventory, see Seed pipe across phases.
2	Introspection + `execute_graphql`	When no dedicated tool exists or a tool fails unexpectedly. See skills/introspection/pipefy-introspection/SKILL.md.
3	Direct HTTP via curl / httpx (this skill)	When the MCP server itself is unavailable, or `execute_graphql` fails with an infrastructure error.

Do not jump to Tier 3 after a single tool failure. Follow the tiers in order.

层级	方法	适用场景
1	专用MCP工具（ `create_card` 、 `get_phase_cards` 、 `get_phase_allowed_move_targets` 、 `update_pipe` 等）	始终优先尝试。如需卡片/阶段初始化和清单管理，请参阅跨阶段初始化管道。
2	自省 + `execute_graphql`	当没有专用工具或工具意外失效时使用。请参阅skills/introspection/pipefy-introspection/SKILL.md。
3	通过curl / httpx直接发起HTTP请求（本技能）	当MCP服务器本身不可用，或 `execute_graphql` 因基础设施错误失效时使用。

请勿在单次工具失效后直接跳到第3层。请按层级顺序执行。

Authentication

身份验证

Two options (use whichever is available in the environment). Prefer the Service Account when both exist.

Option A — OAuth2 Client Credentials (preferred):

bash

TOKEN=$(curl -s -X POST https://app.pipefy.com/oauth/token \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$PIPEFY_SERVICE_ACCOUNT_CLIENT_ID\",\"client_secret\":\"$PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

Option B — Personal Access Token (PAT):

bash

TOKEN="$PIPEFY_PAT"   # or $PIPEFY_TOKEN

PATs are deprecated for new integrations but may still exist in the environment.

两种选项（使用环境中可用的任意一种）。若两者都存在，优先选择服务账号。

选项A — OAuth2客户端凭证（优先选择）：

bash

TOKEN=$(curl -s -X POST https://app.pipefy.com/oauth/token \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$PIPEFY_SERVICE_ACCOUNT_CLIENT_ID\",\"client_secret\":\"$PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

选项B — 个人访问令牌（PAT）：

bash

TOKEN="$PIPEFY_PAT"   # or $PIPEFY_TOKEN

PAT已被弃用，不再用于新集成，但环境中可能仍存在。

Token rules

令牌规则

The
```
Bearer 
```
prefix is mandatory — Pipefy rejects requests without it.

Never expose

PIPEFY_SERVICE_ACCOUNT_CLIENT_ID

PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET

PIPEFY_PAT

, or

PIPEFY_TOKEN

in responses to the user or in logs.

Service Account tokens are reused while valid; only re-fetch on expiry (401).

```
Bearer 
```
前缀是必填项——Pipefy会拒绝不带该前缀的请求。

切勿在用户响应或日志中暴露

PIPEFY_SERVICE_ACCOUNT_CLIENT_ID

、

PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET

、

PIPEFY_PAT

或

PIPEFY_TOKEN

。

服务账号令牌在有效期内可重复使用；仅在过期（401错误）时重新获取。

Endpoints

端点

Purpose	URL
All queries and mutations	`https://api.pipefy.com/graphql`
Schema introspection only	`https://app.pipefy.com/graphql`
OAuth2 token	`https://app.pipefy.com/oauth/token`

Real operations go to

api.pipefy.com

; introspection goes to

app.pipefy.com

. The MCP server and CLI route between the two automatically (both derived from

PIPEFY_BASE_URL

); raw-API users must distinguish them by hand.

用途	URL
所有查询和变更	`https://api.pipefy.com/graphql`
仅架构自省	`https://app.pipefy.com/graphql`
OAuth2令牌	`https://app.pipefy.com/oauth/token`

实际操作请求发送至

api.pipefy.com

；自省请求发送至

app.pipefy.com

。MCP服务器和CLI会自动在两者间路由（均基于

PIPEFY_BASE_URL

）；使用原生API的用户需手动区分。

Execute a GraphQL query

执行GraphQL查询

bash

curl -s -X POST https://api.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id name } }"}' | jq .

bash

curl -s -X POST https://api.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id name } }"}' | jq .

Execute a GraphQL mutation

执行GraphQL变更

bash

curl -s -X POST https://api.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateCard($input: CreateCardInput!) { createCard(input: $input) { card { id } } }",
    "variables": {
      "input": {
        "pipe_id": 67890,
        "title": "Fallback Card"
      }
    }
  }' | jq .

bash

curl -s -X POST https://api.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateCard($input: CreateCardInput!) { createCard(input: $input) { card { id } } }",
    "variables": {
      "input": {
        "pipe_id": 67890,
        "title": "Fallback Card"
      }
    }
  }' | jq .

When to use direct API vs MCP tools

何时使用直接API vs MCP工具

Situation	Use
MCP server running normally	MCP tools (Tier 1 or 2)
MCP server down / unreachable	Direct API (Tier 3)
`execute_graphql` returns 500 error	Direct API (Tier 3)
Testing a new mutation before MCP tool exists	`execute_graphql` (Tier 2) — not direct API

场景	选择方案
MCP服务器正常运行	MCP工具（第1层或第2层）
MCP服务器宕机/无法访问	直接API（第3层）
`execute_graphql` 返回500错误	直接API（第3层）
在MCP工具存在前测试新变更	`execute_graphql` （第2层）——而非直接API

Introspection via raw API

通过原生API进行自省

When you need to discover schema without MCP tools, call

app.pipefy.com/graphql

bash

undefined

当你需要在没有MCP工具的情况下发现架构时，调用

app.pipefy.com/graphql

：

bash

undefined

All queries and mutations

所有查询和变更

curl -s -X POST https://app.pipefy.com/graphql
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"query":"{ __schema { queryType { fields { name description } } mutationType { fields { name description } } } }"}'

Type details

类型详情

curl -s -X POST https://app.pipefy.com/graphql
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"query":"{ __type(name: "CreateCardInput") { inputFields { name description type { name kind ofType { name kind } } } } }"}'

---

---

Error code → cause

错误码→原因

GraphQL always returns HTTP 200, even on errors. Check the

errors

array, not the HTTP status code.

Code	Likely cause	Recovery
UNAUTHORIZED	Token missing, expired, or `Bearer` omitted	Re-fetch token (Option A) or fix the header.
PERMISSION_DENIED	Service Account not a member of this pipe/table	Add SA via `invite_members` or ask user.
resource_not_found	ID does not exist or SA cannot see it	Verify ID; check pipe/table membership.
invalid_input	Wrong argument name or type	Run `introspect_type` (Tier 2) to recheck the input shape.
INTERNAL_SERVER_ERROR	API bug or unsupported payload	Do NOT retry the same payload. Try an alternative mutation or workaround.
missingRequiredInputObjectAttribute	A required field is missing from the input	Compare the payload against `__type(name: …InputType)` .

GraphQL始终返回HTTP 200，即使出现错误。请检查

errors

数组，而非HTTP状态码。

代码	可能原因	恢复措施
UNAUTHORIZED	令牌缺失、过期或遗漏 `Bearer` 前缀	重新获取令牌（选项A）或修复请求头。
PERMISSION_DENIED	服务账号不是该管道/表格的成员	通过 `invite_members` 添加服务账号或联系用户。
resource_not_found	ID不存在或服务账号无法查看	验证ID；检查管道/表格成员身份。
invalid_input	参数名称或类型错误	运行 `introspect_type` （第2层）重新检查输入格式。
INTERNAL_SERVER_ERROR	API bug或不支持的负载	请勿重试相同负载。尝试替代变更或解决方案。
missingRequiredInputObjectAttribute	输入中缺少必填字段	将负载与 `__type(name: …InputType)` 进行对比。

Known workarounds

已知解决方案

Cross-pipe

create_card

via automation

通过自动化跨管道

create_card

Do NOT use

createAutomation

with

action: create_card

field_map

— returns

INTERNAL_SERVER_ERROR

(confirmed API bug).

Instead, use
```
createCard
```
with the
```
throughConnectors
```
parameter. Prerequisite: a connector field with
```
canCreateNewConnected: true
```
must exist.

请勿使用

createAutomation

搭配

action: create_card

field_map

——会返回

INTERNAL_SERVER_ERROR

（已确认的API bug）。

替代方案：使用带有
```
throughConnectors
```
参数的
```
createCard
```
。前提条件：必须存在一个
```
canCreateNewConnected: true
```
的连接器字段。

Pipe visibility returning empty list

管道可见性返回空列表

If
```
organization { pipes { ... } }
```
returns
```
[]
```
but
```
pipesCount > 0
```
, the Service Account is not a member of those pipes.
Pipes created via API are automatically visible to the SA.
Pipes created in the UI require the SA to be added as an admin.
Workaround: get pipe IDs from the user once and query
```
pipe(id: "...")
```
directly.

如果
```
organization { pipes { ... } }
```
返回
```
[]
```
但
```
pipesCount > 0
```
，说明服务账号不是这些管道的成员。
通过API创建的管道会自动对服务账号可见。
在UI中创建的管道需要将服务账号添加为管理员。
解决方案：从用户处获取一次管道ID，然后直接查询
```
pipe(id: "...")
```
。

invite_members

accepts unknown emails silently

invite_members

静默接受无效邮箱

Pipefy mints a new
```
user_id
```
for typo addresses without rejecting the invite. Sanity-check email syntax before calling.

Pipefy会为拼写错误的地址生成新的
```
user_id
```
，而不会拒绝邀请。调用前请检查邮箱格式是否正确。

External resources (when raw API also fails)

外部资源（当原生API也失效时）

Pipefy developer portal:
API reference:
- https://api-docs.pipefy.com/reference/mutations/overview/
- https://api-docs.pipefy.com/reference/queries/overview/
Community + changelog:
- https://community.pipefy.com/api-76
- https://developers.pipefy.com/changelog
Status page: https://status.pipefy.com

Search for the exact error message + "Pipefy GraphQL", or the mutation name + "example Pipefy API".

Pipefy开发者门户：
API参考：
- https://api-docs.pipefy.com/reference/mutations/overview/
- https://api-docs.pipefy.com/reference/queries/overview/
社区+更新日志：
- https://community.pipefy.com/api-76
- https://developers.pipefy.com/changelog
状态页面：https://status.pipefy.com

搜索精确的错误信息 + "Pipefy GraphQL"，或变更名称 + "example Pipefy API"。

Escalation to the user (absolute last resort)

上报给用户（绝对最后手段）

Only after all 3 tiers and external resources have failed:

State exactly what was tried (MCP tool, introspection, raw API).
Show the verbatim error response.
Propose a concrete workaround (e.g., "create via the Pipefy UI, then continue via API with the resulting ID").
Stop — do not loop.

仅在所有3层方案和外部资源都失效后执行：

准确说明已尝试的方案（MCP工具、自省、原生API）。
展示完整的错误响应内容。
提出具体的解决方案（例如：“通过Pipefy UI创建，然后使用生成的ID继续通过API操作”）。
停止操作——请勿循环尝试。

Success criteria

成功标准

The operation completes without an HTTP 4xx/5xx error.
The response contains a
```
data
```
key and
```
errors
```
is null or absent.

操作完成且无HTTP 4xx/5xx错误。
响应包含
```
data
```
键，且
```
errors
```
为null或不存在。

Failure modes

失败模式

401 Unauthorized — token expired or
```
Bearer 
```
prefix omitted. Re-fetch the OAuth token (Option A).
400 Bad Request — GraphQL syntax error. Validate the query string and escape quotes properly when embedding via shell.
500 / service unavailable — Pipefy API outage. Check status.pipefy.com and retry later. Do not loop.
INTERNAL_SERVER_ERROR
in
errors
array — do NOT retry the same payload; pick a different mutation path.

401 Unauthorized — 令牌过期或遗漏
```
Bearer 
```
前缀。重新获取OAuth令牌（选项A）。
400 Bad Request — GraphQL语法错误。验证查询字符串，并在通过shell嵌入时正确转义引号。
500 / service unavailable — Pipefy API故障。查看status.pipefy.com并稍后重试。请勿循环尝试。
errors
数组中的
INTERNAL_SERVER_ERROR
— 请勿重试相同负载；选择其他变更路径。

Security notes

安全说明

Never log or print tokens in plain text.
Prefer environment variables over inline credentials.
Use
```
PIPEFY_TOKEN
```
/
```
PIPEFY_PAT
```
only for personal/development use; use service-account credentials (
```
PIPEFY_SERVICE_ACCOUNT_CLIENT_ID
```
+
```
PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET
```
) for service accounts.

请勿以明文形式记录或打印令牌。
优先使用环境变量而非内联凭证。

PIPEFY_TOKEN

PIPEFY_PAT

仅用于个人/开发用途；服务账号请使用服务账号凭证（

PIPEFY_SERVICE_ACCOUNT_CLIENT_ID

PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET

）。

另请参阅

skills/introspection/pipefy-introspection/SKILL.md — Tier 2: use
```
execute_graphql
```
and introspection tools through the MCP server before falling back to direct HTTP.

skills/introspection/pipefy-introspection/SKILL.md — 第2层：在回退到直接HTTP请求前，通过MCP服务器使用
```
execute_graphql
```
和自省工具。

pipefy-api-fallback

Original

Translation

Pipefy API Fallback (Tier 3 — Last Resort)

Pipefy API 备用方案（第3层——最后手段）

3-tier resolution strategy (always follow in order)

三层解决策略（务必按顺序执行）

Authentication

身份验证

Token rules

令牌规则

Endpoints

端点

Execute a GraphQL query

执行GraphQL查询

Execute a GraphQL mutation

执行GraphQL变更

When to use direct API vs MCP tools

何时使用直接API vs MCP工具

Introspection via raw API

通过原生API进行自省

All queries and mutations

所有查询和变更

Type details

类型详情

Error code → cause

错误码→原因

Known workarounds

已知解决方案

Cross-pipe create_card via automation

通过自动化跨管道create_card

Pipe visibility returning empty list

管道可见性返回空列表

invite_members accepts unknown emails silently

invite_members静默接受无效邮箱

External resources (when raw API also fails)

外部资源（当原生API也失效时）

Escalation to the user (absolute last resort)

上报给用户（绝对最后手段）

Success criteria

成功标准

Failure modes

失败模式

Security notes

安全说明

See also

另请参阅

Cross-pipe
`create_card`
via automation

通过自动化跨管道
`create_card`

`invite_members`
accepts unknown emails silently

`invite_members`
静默接受无效邮箱