公開APIでタスクを連携する
公開REST APIは /api/v1 で提供しています。ボード構成とメンバーの参照、タスクとコメントの操作に使えます。各リクエストとレスポンスの詳細はAPIリファレンスを参照してください。
アカウント設定の「APIトークン」から、対象ワークスペースのトークンを発行します。トークンは発行時に一度だけ表示されます。外部システムのシークレット設定で保管してください。
すべてのリクエストに、次のヘッダーを指定します。
Authorization: Bearer <APIトークン>X-Tenant-Id: <ワークスペースID>
readトークンは参照のみ、read/writeトークンは更新にも使えます。発行者の現在のワークスペース・ボード権限も適用されます。失効・期限切れ・ワークスペースからの脱退後は利用できません。
最初のタスクを作る
Section titled “最初のタスクを作る”APIのオリジン、ワークスペースID、トークンを、それぞれ UTSUROI_API_URL、UTSUROI_TENANT_ID、UTSUROI_API_TOKEN に設定した例です。
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を指定してタスクを作ります。
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 で返します。タスクの作成日時と更新日時、親子関係、担当者などは一覧と詳細で同じ形式です。コメントは専用エンドポイントで取得します。
ページングと検索
Section titled “ページングと検索”タスク、ボード、メンバー、コメントの一覧は、既定50件、最大100件です。limit で件数を指定し、返された nextCursor を次のリクエストの cursor に渡します。nextCursor: null が最後のページです。
作成日時、同時刻ならIDの昇順です。コメントは投稿日時を使います。タスクは q でタイトル・説明を検索でき、boardId、laneId、parentId、assigneeId、labelId、projectId で絞り込めます。archived は exclude(既定)、include、only です。
次のページも同じフィルターを指定してください。カーソルはワークスペース・利用者・一覧の種類・フィルターに紐づくため、別の検索には使えません。条件に合うタスクだけを返し、親や子は自動で追加しません。ページング中の追加・削除・条件変更は反映されるため、全ページが同一時点のスナップショットになる保証はありません。
エラーと互換性
Section titled “エラーと互換性”エラーは { "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はエージェント連携で案内しています。