pipefy-attachments

添付ファイル

MCP クライアント： references/mcp.md をお読みください。CLI ユーザー： references/cli.md をお読みください。以下の例では、共通の操作引数について説明します。

カードまたはテーブルレコードの添付ファイルフィールドに、一度に 1 つのファイルをアップロードします。アップロードは Pipefy の署名付き URL フロー（URL のリクエスト、S3 への PUT、その後のフィールド更新）を経由します。

---

使用するタイミング

• ユーザーが「このファイルをカード X に添付して」または「レコード Y の書類フィールドにアップロードして」と指示した場合。
• バイトデータの実際の保存場所に基づいてソースを選択します。選択したインターフェースに応じたソースのルールを使用してください。

このスキルは次の用途には使用しないでください。

• 既存の添付ファイルの読み取りや一覧表示。このスキルの対象範囲には、一覧表示／ダウンロードツールはありません。カードとテーブルレコードの添付ファイルは、通常のカード／レコード取得ツールで確認できます。
• 一括アップロード。1 回の呼び出しにつき 1 ファイルです。エージェント層で繰り返し処理してください。

前提条件

• Pipefy の organization_id。get_organization または get_pipe で確認します。
• 対象の card_id または table_record_id。
• 添付ファイルフィールドのスラッグ（document_upload のような人が読める ID であり、フィールドの UUID ではありません）。カードまたはテーブルレコードの取得ツールで確認します。
• 選択したアップロードインターフェースからアクセスできるファイルソースが 1 つだけあること。

必要なツール

操作	読み取り専用
upload_attachment_to_card	いいえ
upload_attachment_to_table_record	いいえ
create_attachment_presigned_url	いいえ

手順

ローカルファイルをカードにアップロードする

file_name を省略すると、ソースのベース名から推定されるため、通常、呼び出し側が渡すのは 4 つの ID とソースだけです。

操作の引数：

upload_attachment_to_card(organization_id=42, card_id=1234, field_id=document_upload, file_path=~/report.pdf)

URL からアップロードする

upload_attachment_to_card(organization_id=42, card_id=1234, field_id=document_upload, file_url=https://example.com/report.pdf)

URL のパスにファイル名が含まれていない場合（例：.../download?id=1）は、Pipefy が実際のファイル名で保存できるよう、file_name を明示的に渡してください。

ローカルファイルをテーブルレコードにアップロードする

操作の引数：

upload_attachment_to_table_record(organization_id=42, table_record_id=tr-555, field_id=document_upload, file_path=/tmp/export.csv)

ファイル名を上書きする

ソースのベース名とは異なる名前で添付ファイルを保存するには、file_name を明示的に渡してください。指定した名前は、推定されたベース名より優先されます。

upload_attachment_to_card(..., file_url=https://example.com/abc123.pdf, file_name=Invoice-2026.pdf)

署名付き URL のハンドシェイクを使用する

ワンショットアップロードでバイトデータにアクセスできない場合、または上限の 100 MiB を超える場合は、create_attachment_presigned_url を使用し、ファイルを読み取れる環境からアップロードしてください。

1. organization_id と file_name（省略可能な content_type／content_length）を指定して create_attachment_presigned_url を呼び出します。upload_url（S3 PUT URL）、storage_path（オブジェクトキー）、expires_in_seconds が返されます。
2. アップロード先ホストにアクセスできる環境から、expires_in_seconds 以内にファイルのバイトデータを upload_url に HTTP PUT します（指定した場合は、値が一致する Content-Type／Content-Length を送信します）。
3. update_card_field／set_table_record_field_value を使って、添付ファイルフィールドに [storage_path] を設定します。URL ではなく storage_path を保存してください。署名付きダウンロード URL は読み取り時に生成されます。

バイトデータはツール呼び出しに渡されず、クライアントが手順 2 で処理するため、モデルのコンテキストをクリーンに保てます。

成功条件

upload_attachment_to_card／upload_attachment_to_table_record（ワンショット）：アップロード結果に download_url（Pipefy が返す署名付き URL）、推定または明示された content_type、バイト単位の file_size が含まれ、カードまたはレコードの添付ファイルフィールドにファイルが表示されていること。1 回の呼び出しで完了します。

create_attachment_presigned_url（ハンドシェイク）は、URL の生成時点では完了していません。ここで成功結果が返っても、アップロード先が生成されたことを意味するだけです。フィールドはまだ変更されておらず、何も添付されていません。完了とは、3 つの手順をすべて終えることです。つまり、クライアントが upload_url にバイトデータを PUT し、フィールドに [storage_path] を設定した後、添付ファイルフィールドにファイルが表示されている状態です。URL の生成結果（または早まって発行された署名付き URL）を、アップロードの完了とみなさないでください。

失敗する場合

ソースへのアクセス、100 MiB の一括アップロード上限、アップロードの有効期限と署名付きヘッダー、添付フィールドへの書き込み権限を確認してください。署名付き URL の有効期限が切れた場合は、新しい URL を発行してください。古い URL に対する PUT を再試行しても、有効期限は更新されません。署名付き URL のハンドシェイクでは、クライアントによる PUT とフィールドの更新を、URL の発行とは別に確認する必要があります。

関連項目

• pipefy-pipes-and-cards：カード ID と添付フィールドのスラッグを確認します。
• pipefy-database-tables：テーブルレコード ID とフィールドのスラッグを確認します。