コンテンツにスキップ

公開APIでタスクを連携する

公開REST APIは /api/v1 で提供しています。ボード構成とメンバーの参照、タスクとコメントの操作に使えます。各リクエストとレスポンスの詳細はAPIリファレンスを参照してください。

アカウント設定の「APIトークン」から、対象ワークスペースのトークンを発行します。トークンは発行時に一度だけ表示されます。外部システムのシークレット設定で保管してください。

すべてのリクエストに、次のヘッダーを指定します。

  • Authorization: Bearer <APIトークン>
  • X-Tenant-Id: <ワークスペースID>

readトークンは参照のみ、read/writeトークンは更新にも使えます。発行者の現在のワークスペース・ボード権限も適用されます。失効・期限切れ・ワークスペースからの脱退後は利用できません。

APIのオリジン、ワークスペースID、トークンを、それぞれ UTSUROI_API_URL、UTSUROI_TENANT_ID、UTSUROI_API_TOKEN に設定した例です。

Terminal window
curl "$UTSUROI_API_URL/api/v1/boards" \
-H "Authorization: Bearer $UTSUROI_API_TOKEN" \
-H "X-Tenant-Id: $UTSUROI_TENANT_ID"

ボードIDを使って GET /api/v1/boards/{id} を呼び出すと、そのボードのレーン・ラベル・プロジェクトを取得できます。ボードIDとレーンIDを指定してタスクを作ります。

Terminal window
curl "$UTSUROI_API_URL/api/v1/tasks" \
-H "Authorization: Bearer $UTSUROI_API_TOKEN" \
-H "X-Tenant-Id: $UTSUROI_TENANT_ID" \
-H 'Content-Type: application/json' \
--data '{"id":"your-unique-id","boardId":"your-board-id","laneId":"your-lane-id","title":"APIから作成"}'

id は省略すると自動生成されます。同じIDで再度作成すると409が返り、既存タスクは上書きされません。通信が途切れて作成結果が分からない場合に備え、連携側でIDを決めておくと、そのIDで取得して結果を確認できます。

  • 基本項目の編集は PATCH /api/v1/tasks/{id} です。省略した項目は保持し、nullableの項目に null を渡すとクリアします。説明を編集しても、担当者・ラベル・コメントは保持されます。
  • 担当者とラベルは、それぞれ /assignees と /labels へのPUTで集合全体を置き換えます。
  • 開始・完了・再開は /start・/complete・/reopen へのPOSTです。レーン・日時・履歴も更新します。
  • /move-to-board は移動先に新しいIDでコピーし、元タスクをアーカイブします。元のIDは引き継ぎません。
  • コメントは /comments、リアクションは /comments/{commentId}/reactions で操作します。コメントの編集・削除は投稿者に限られます。

日付は YYYY-MM-DD、作成・更新・開始・完了などの時刻はUnix epochのミリ秒です。未設定のタスク項目は null で返します。タスクの作成日時と更新日時、親子関係、担当者などは一覧と詳細で同じ形式です。コメントは専用エンドポイントで取得します。

タスク、ボード、メンバー、コメントの一覧は、既定50件、最大100件です。limit で件数を指定し、返された nextCursor を次のリクエストの cursor に渡します。nextCursor: null が最後のページです。

作成日時、同時刻ならIDの昇順です。コメントは投稿日時を使います。タスクは q でタイトル・説明を検索でき、boardId、laneId、parentId、assigneeId、labelId、projectId で絞り込めます。archived は exclude(既定)、include、only です。

次のページも同じフィルターを指定してください。カーソルはワークスペース・利用者・一覧の種類・フィルターに紐づくため、別の検索には使えません。条件に合うタスクだけを返し、親や子は自動で追加しません。ページング中の追加・削除・条件変更は反映されるため、全ページが同一時点のスナップショットになる保証はありません。

エラーは { "error": { "code": "…", "message": "…" } } です。処理の分岐にはHTTPステータスと code を使ってください。

  • 400:入力やカーソルが不正です。
  • 401:トークンが無効です。402:プランの制限により操作できません。
  • 403:トークンまたは利用者の権限が不足しています。
  • 404:対象がありません。409:IDなどが競合しています。422:参照先や操作が不正です。
  • 429:レート制限です。Retry-After の秒数を待ってください。読み取りと書き込みは別枠で、同じ利用者の複数トークンは枠を共有します。

上限は 1 分あたりの回数で、プランごとに決まっています。

プラン 読み取り 書き込み
Free 60 回 30 回
Pro 600 回 300 回

v1では既存の入力・出力と操作の意味を維持します。新しい任意項目や操作は追加されるため、レスポンスの未知の項目は無視してください。破壊的変更が必要な場合は別のメジャーバージョンを提供し、移行期間を案内します。

ボード・レーン・ラベル・プロジェクトの構成変更、添付ファイル操作、管理・課金・Slack設定は公開REST APIの対象外です。MCPはエージェント連携で案内しています。