使い方ガイド 07

API から使う

OpenAPI 3.1 の仕様書を公開しています。ChatGPT や Claude からは、ログインするだけで繋げます。

Pinateca は API を後付けの機能として持っているのではなく、画面と同じ入口を外にも開けています。仕様書は OpenAPI 3.1 の形で公開しているので、そのURLを渡せば、AI も自動化ツールも呼び方を理解します。

https://pinateca.com/api/openapi.json

トークンを発行する

ワークスペース設定の「APIトークン」から発行します。発行と失効のときだけ、自分のパスワードをもう一度入れてもらいます。トークンは発行の直後にしか表示されないので、その場で控えてください。

APIトークンの発行画面
APIトークン。名前と有効期限を付けて発行します。最後に使われた日時が残るので、使っていないトークンはすぐ分かります。
  1. 発行できるのはオーナーだけワークスペース単位で持ちます。権限は管理者と同じです。
  2. 有効期限を付けられる短期の連携なら期限を切ってください。過ぎたトークンは自動で使えなくなります。
  3. いつでも失効させられる漏れた心当たりがあれば、その場で無効にできます。

呼び方

共通の入口は https://pinateca.com/api です。発行したトークンを Authorization ヘッダに載せます。

curl https://pinateca.com/api/boards \
  -H "Authorization: Bearer kbn_xxxxxxxxxxxx"

カードを1枚足すなら、こうです。

curl https://pinateca.com/api/cards \
  -H "Authorization: Bearer kbn_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"listId": 123, "title": "見積書を送る"}'

応答は素の JSON です。入れ物で包んでいないので、そのまま扱えます。うまくいかないときは理由が返ります。 {"error": "..."}

できること

口ごとの詳しい形（渡すもの・本体・返り）は API仕様書 にまとめています。あの画面は仕様書そのものから作っているので、実際の口とずれません。

対象できること
ボード一覧、詳細（リストとカードごと）、作成、更新、アーカイブ、並べ替え
カード作成、詳細、更新、削除、リストをまたぐ並べ替えと移動
リスト（セル）名前と付随情報の更新
グリッド・時間割列と行の取得
ガントチャート工程の取得、期間の更新、並べ替え
カスタムフィールド項目の作成・削除、ボード全体の値の取得、カードごとの値の設定

AI から使う

ChatGPT と Claude は、Pinateca の住所を入れて、ログインして許可するだけで繋がります。トークンを発行して貼る必要はありません。

  1. ChatGPT設定で開発者モードをオンにし、アプリを作る画面で、MCP サーバーの URL に https://pinateca.com/mcp、認証に OAuth を選びます。開発者モードは有料プラン（Plus・Pro・Business など）で使えます。
  2. Claude（claude.ai・Claude Desktop）コネクタの設定で、カスタムコネクタとして https://pinateca.com/mcp を追加します。
  3. Claude Codeclaude mcp add --transport http pinateca https://pinateca.com/mcp で追加し、/mcp からログインします。
  4. Pinateca の画面で許可するどの AI から繋いでも、Pinateca のログイン画面が開きます。ログインして、繋ぐワークスペースを選び、許可するを押せば終わりです。
AI から繋いだときに開く、許可の画面
AI から繋いだときに開く、許可の画面

ログインして繋いだ AI は、あなたの権限の範囲でだけ動きます。あなたが見られないボードは AI からも見られず、契約やトークンの発行には触れません。繋いだ AI はワークスペース設定の「APIトークン」に名前付きで並ぶので、止めたいときはそこで失効させてください。

どちらの繋ぎ方でも、ボードの一覧と中身、カードの作成・更新・移動・削除、リスト名の変更、自由項目の読み書き、ガントの工程まで扱えます。「今週締切のカードを一覧にして」「議事録から決まったことをカードにして」といった頼み方が、そのまま動く状態になります。

トークンで繋ぐ

ログインの画面を挟めない使い方では、ワークスペース設定で発行したトークンを使います。

  1. ChatGPT の GPTsActions に https://pinateca.com/api/openapi.json を読み込ませ、認証を API Key（Bearer）にしてトークンを入れます。
  2. 手元で動かす MCPclaude mcp add pinateca -e PINATECA_TOKEN=kbn_xxx -- npx -y pinateca-mcp の1行で入ります。Claude Desktop は設定ファイルに同じものを書きます。
トークンはワークスペースの中身に手が届く鍵です。外部サービスに預けるときは、有効期限を付けて、使わなくなったら失効させてください。最後に使われた日時が画面に出るので、放置されたトークンはそこで見つかります。

出来事を受け取る（Webhook）

こちらから呼ぶだけでなく、Pinateca 側から知らせを送ることもできます。カードが動いた、コメントが付いた、担当者が変わったといった出来事を、起きたその場で指定のURLへ POST します。定期的に取りに来る必要がないので、反応が速く、無駄な問い合わせも起きません。

送信先はワークスペース設定の「Webhook」から登録します。受け取りたい出来事だけを選べます。API から登録することもできます。

curl https://pinateca.com/api/webhooks \
  -H "Authorization: Bearer kbn_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hook", "events": ["card.create", "card.move"]}'

届く中身はこの形です。

{
  "id": 1234,
  "event": "card.create",
  "occurredAt": "2026-09-02T11:20:00.000Z",
  "workspace": { "slug": "acme", "name": "株式会社アクメ" },
  "boardId": 12,
  "actor": { "memberId": 3, "name": "佐藤 陽菜" },
  "data": { "id": 987, "title": "見積書を送る", "listName": "未着手", "dueDate": null }
}

本物かどうかを確かめる

送信先を作ると whsec_ で始まる鍵が1度だけ表示されます。こちらは本文をこの鍵で計算した値を X-Pinateca-Signature ヘッダに載せて送るので、受け取る側で同じ計算をして突き合わせれば、他人が投げた偽物を弾けます。

const expected =
  'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
if (req.headers['x-pinateca-signature'] !== expected) return res.status(401).end();

届かなかったときは

30秒後、2分後、10分後、1時間後、6時間後の順で送り直します。それでも届かなければ諦めますが、送信の記録は設定画面に残るので、いつ何が返ってきたかを後から確認できます。連続して失敗し続けた送信先は自動で止まります。

Zapier のように連携ツール側から購読を作りに来る使い方（REST Hook）にも対応しています。口の詳しい形は API仕様書 をご覧ください。

n8n から使う

自動化ツールの n8n には、専用のノードを公開しています。n8n の 設定 → コミュニティノード で n8n-nodes-pinateca と入れれば、カードの作成や更新に加えて、カードが動いた瞬間に動き出すきっかけとして使えます。仕組みは上の Webhook そのままなので、購読の登録と解除も n8n が自分で行います。

Zapier と Pabbly Connect は審査に申請中、Make は用意しているところです。詳しくは 外部サービスとの連携 をご覧ください。

前の章稼働タイムシート次に読むよくある質問