compare
Backlog APIの使い方を調べている人の目的は、たいてい1つです。毎週誰かが手で写している表を、機械に写させたい。課題の一覧をスプレッドシートに貼る作業、進捗を報告書に転記する作業、依頼メールから課題を起こす作業。この記事では、公式ドキュメントに書かれている範囲だけを材料に、認証の選び方、最初の1本の通し方、課題の取得と登録、そして先に読んでおくべき回数制限までを順番に並べます。手を動かす前に読む順番が分かる状態を目指します。
APIを使い始めるとき、最初にやることはコードを書くことではありません。いま人がやっている作業のうち、どれを機械に渡すかを1つに決めることです。ここを決めずに始めると、認証が通った時点で満足して、その後のつなぎ込みが半端に終わります。
渡す価値が高い作業には特徴があります。毎週決まった曜日に発生し、手順が決まっており、間違えると誰かが困る。この3つが揃っている作業です。具体的には、期限切れの課題を洗い出して一覧にする作業、担当者別の残件数を数える作業、決まった書式の課題をまとめて起こす作業が当てはまります。
逆に、渡すのを後回しにしたほうがよい作業もあります。判断が混じるものです。どの課題を優先するか、誰に振り替えるか、締切を延ばしてよいかという判断は、APIで動かす部分ではありません。機械に渡すのはデータの移動と集計だけにして、判断は人に残す形が安定します。
決め方の目安として、その作業に月何時間かかっているかを数えてください。毎週30分の転記なら、1年で26時間です。半日で書ける仕組みなら十分に見合います。逆に月10分の作業をAPIで自動化すると、仕組みの面倒を見る時間のほうが長くなります。数えてから決めるのと、勢いで始めるのとでは、続くかどうかが変わります。
対象が決まったら、その作業に必要なデータだけを取りに行きます。課題の一覧が欲しいのか、コメントまで欲しいのか、添付まで欲しいのか。必要なものが少ないほど、回数制限にも当たりにくくなります。
Backlog APIを呼ぶには、APIキーかOAuth 2.0のアクセストークンのどちらかが必要です。公式ドキュメントでは、APIキーがいちばん手軽な方法として案内されており、Backlogにログインして個人設定のAPIの画面から発行する形になっています。
APIキーの渡し方は2つあります。1つはURLのクエリパラメータとして「apiKey」に付ける形、もう1つは「Backlog-API-Key」というリクエストヘッダに入れる形です。どちらでも同じように動きますが、実務ではヘッダに入れるほうを勧めます。クエリパラメータに入れると、アクセスログや共有したURLにキーがそのまま残るからです。手元で試すときだけクエリパラメータを使い、仕組みに組み込むときはヘッダに移す、という切り替えが現実的です。
OAuth 2.0は、自分以外のBacklogユーザーの代わりにAPIを呼ぶ場合に使う方式として案内されています。仕組みは「The OAuth 2.0 Authorization Framework」で定義された認可コード付与の流れで、先にBacklogの開発者向けサイトでアプリケーションを登録し、client_idとclient_secretを受け取ります。認可のリクエストはGETで/OAuth2AccessRequest.actionへ送り、利用者が許可すると、登録したリダイレクト先に認可コードが返ります。そのコードを使ってPOSTで/api/v2/oauth2/tokenを呼ぶと、アクセストークンとリフレッシュトークンが返ってきます。
押さえておくべき数字が1つあります。アクセストークンの有効期間は3600秒、つまり1時間です。1時間を超えて動かす仕組みでは、リフレッシュトークンを使って取り直す処理が必ず必要になります。毎朝1回だけ動かすバッチなら毎回取り直すだけで済みますが、常駐して動く仕組みなら、期限切れを見てから取り直す流れを最初から組んでおかないと、深夜に静かに止まります。
社内で使う集計の仕組みを1つ作るだけなら、APIキーで十分です。他人のアカウントの代わりに動く必要が出てから、OAuth 2.0に移ってください。最初からOAuth 2.0で組むと、アプリ登録とリダイレクトの設定で半日使い、肝心の集計に手が回りません。
認証情報が手に入ったら、次にやるのは自分の情報を取る1本だけです。公式のはじめかたのページでも、/api/v2/users/myself を最初に呼んで、認証が正しく設定できているかを確かめる手順が案内されています。
呼び先の形はこうなります。
curl -H "Backlog-API-Key: YOUR_API_KEY" \
"https://YOUR-SPACE.backlog.jp/api/v2/users/myself"
URLの土台については、次のように整理されています。
https://{スペース名}.backlog.jp/api/v2/{エンドポイント}実務でよく使われる代表的なエンドポイントには、以下のようなものがあります。 出典: depart-inc.com
ここでつまずく人がいちばん多いのが、ドメインの部分です。スペースのURLがbacklog.jpのチームと、backlog.comのチーム、そして古くからのbacklogtool.comのチームがあり、公式ドキュメントにも両方の例が併記されています。自分のスペースをブラウザで開いたときのアドレスをそのまま使うのが確実です。ここが違うと、キーが正しくても認証に失敗します。
成功すると、HTTPの200が返り、自分のユーザーID、名前、権限を表す値、メールアドレスがJSONで返ってきます。失敗したときは4xxか5xxが返り、本文にerrorsという配列が入ります。配列の中にはmessageとcodeが入り、認証に失敗した場合のcodeは11です。ドキュメントには、よくある原因としてキーが間違っているかスペースが違う場合、そしてアクセストークンの期限が切れた場合の2つが挙げられています。
OAuth 2.0のときだけ、失敗の返り方が違います。401が返り、エラーの内容はerrorsの本文ではなくWWW-Authenticateというレスポンスヘッダに入ります。トークンが無効なのか期限切れなのかもそのヘッダに書かれるので、OAuth 2.0で組むならヘッダを読む処理を入れておいてください。本文だけを見ていると、原因が分からないまま401を眺めることになります。
いちばん使われるのが課題の一覧を取る呼び出しです。GETで/api/v2/issuesを呼びます。ここで大事なのは、引数を覚えることよりも、絞り込まずに呼ばないことです。
1回で返る件数は引数のcountで指定し、指定できる範囲は1から100まで、省略したときは20件です。つまり課題が500件あるスペースで全部を取るには、offsetをずらしながら5回以上呼ぶことになります。ここを知らずに1回呼んで「20件しか返ってこない」と悩む人が多い部分です。
絞り込みの引数は豊富に用意されています。プロジェクトを指定するprojectId、状態で絞るstatusId、担当者で絞るassigneeId、種別で絞るissueTypeId、マイルストーンで絞るmilestoneIdは、いずれも複数指定できます。並び順はsortとorderで指定し、期限で絞るdueDateSinceとdueDateUntil、更新日で絞るupdatedSinceとupdatedUntilもあります。キーワード検索のkeywordもあります。
実務で効くのはupdatedSinceです。毎朝動かす集計なら、前日以降に更新されたものだけを取れば、呼び出しの回数が一桁減ります。公式の回数制限のページでも、呼び出しを減らす方法としてupdatedSinceのような条件を使うことが勧められています。全件を毎回取り直す作りにしていると、課題が増えたある日に急に制限へ当たります。
子課題の扱いも引数で決まります。parentChildで、子課題を除く、親課題だけ、といった絞り方ができます。さらにexpandにchildIssueSummaryを指定すると、直下の子課題の総数と完了済みの数が応答に含まれます。親課題の進み具合を数えたいだけなら、子課題を全部取ってきて自分で数える必要はありません。
カスタム属性でも絞れます。文字の属性はcustomField_{ID}にキーワードを渡し、数値と日付は_minと_maxで範囲を渡し、リストは値のIDを渡します。自分たちのプロジェクトで属性を作り込んでいるなら、この絞り込みで必要な行だけを取れます。
課題を登録するのはPOSTで/api/v2/issuesです。フォーム形式で送る作りで、必須の引数は4つです。projectId、summary、issueTypeId、priorityId。この4つが揃っていないと作れません。逆に言えば、開始日や期限、担当者、見積時間は後から入れられます。
任意で指定できるものには、親課題のID、説明、開始日と期限、見積時間と実績時間、カテゴリー、マイルストーン、担当者、通知したいユーザー、添付ファイルのID、そしてカスタム属性があります。説明ではメンションの記法が使えるとドキュメントに書かれています。添付は先にファイルを登録するAPIを呼んでIDを受け取り、そのIDを渡す2段構えです。
登録に成功すると、HTTPの201が返り、Locationヘッダに作った課題の表示用URLが入ります。本文には課題キー（BLG-1のような形）を含む課題の中身が返ります。依頼メールから課題を起こす仕組みを作るなら、この課題キーとURLを依頼者へ返す作りにしておくと、後で「あの件どうなった」の問い合わせが減ります。
更新はPATCH、削除はDELETEです。課題のコメントにも、一覧の取得、追加、件数、削除、更新のそれぞれに呼び出しが用意されています。課題以外にも、Wikiページ、ドキュメント、共有ファイル、プロジェクト、ユーザー、状態、種別、カテゴリー、マイルストーン、カスタム属性、GitのリポジトリとプルリクエストにAPIがあります。読み書きできる範囲は広く、公式の概要ページでも、課題やWikiページやファイルといったBacklog上のデータの取得と更新に加えて、プロジェクトとユーザーの管理もできると案内されています。
ブラウザから直接呼ぶ使い方についても触れられています。Backlog APIはオリジン間リソース共有に対応しているため、ブラウザ上のAjaxリクエストで呼べると明記されています。社内向けの小さな画面を1枚作るだけなら、サーバーを立てずに済む場合があります。ただしその作りではAPIキーが利用者のブラウザに渡ることになるので、社内限定の画面に限る判断が必要です。
実際に書き始めると、最初に止まるのは認証ではなくIDです。プロジェクトID、種別ID、優先度ID、マイルストーンID。APIは数字のIDを求めてくるのに、画面に出ているのは名前だけだからです。
正攻法は、それぞれの一覧を取るAPIを先に呼ぶことです。プロジェクトの一覧、プロジェクトごとの状態の一覧、優先度の一覧、種別の一覧、マイルストーンの一覧にそれぞれ呼び出しがあり、名前とIDの対応が返ります。仕組みに組み込むならこの形が正しく、名前を変えられても動き続けます。
手元で試す段階では、画面のURLから拾う手もあります。設定画面を開いたときのアドレスにIDが入っているためで、次のように紹介されています。
マイルストーンならこんな感じ。 https://{スペースの名前}.backlog.jp/EditVersion.action?version.id=xxxxxxxx 出典: qiita.com
この拾い方は速い代わりに、拾ったIDをコードに直接書き込んでしまいがちです。書き込むと、プロジェクトが増えたときや別のスペースで動かすときに全部直すことになります。試すときはURLから拾い、仕組みにするときは一覧を取る呼び出しに置き換える、という2段構えにしておくと後が楽です。
カスタム属性のIDも同じです。属性の一覧を取る呼び出しがあり、そこからIDを得てからcustomField_{ID}の形で指定します。属性を自分たちで作り込んでいるチームほど、ここで手が止まります。最初に属性の一覧を1回取って、名前とIDの対応表を手元に持っておくと、以降の作業が速く進みます。
APIで作った仕組みが数か月後に止まる原因のほとんどが、この回数制限です。作る前に読んでおいてください。
Backlog APIは1分あたりの呼び出し回数に上限を設けており、種類ごとに枠が分かれています。読み取りは検索とアイコンを除くGET、更新はPOSTとPATCHとDELETE、検索は課題一覧と課題数とWikiページ一覧とWikiページ数、アイコンはスペースやユーザーやプロジェクトのアイコン取得です。上限の値は無料プランと有料プランで異なり、いま自分に適用されている上限はGETで/api/v2/rateLimitを呼ぶと取れます。公式ドキュメントに載っている応答の例では、読み取りが1分あたり600、更新が150、検索が150、アイコンが60という値になっています。自分のスペースの実際の値は、この呼び出しで確かめるのが確実です。
上限を超えると、429が返ります。同時に、3つのヘッダが返ってきます。X-RateLimit-Limitがその枠の上限、X-RateLimit-Remainingが残りの回数、X-RateLimit-Resetが枠がリセットされる時刻で、値はUTCのエポック秒です。作る仕組みには、この3つを読んで待つ処理を入れてください。
公式が挙げている推奨のやり方も具体的です。1人のユーザーのリクエストは直列に送り、同時に投げない。更新・検索・アイコンを大量に投げるときは1回ごとに1秒以上待つ。制限に当たったら1分待ってから再試行し、短くしたい場合はX-RateLimit-Resetの値で調整する。過去の応答をためておいて呼び出しを減らす。この4つです。
見落としやすい注意も2つ書かれています。1つは、この制限がAPIキー単位ではなくユーザー単位であること。1人が2つのキーを作っても枠は共通です。もう1つは、Nulabが提供しているツールを使ったときのリクエストも同じ枠に数えられること。GoogleスプレッドシートでのSQL相当の一括登録ツールや、他の課題管理から移すツールを動かしている間に自作の仕組みも動かすと、合計が上限を超えます。並行して動かす予定があるなら、時間をずらしてください。
さらに、複数ユーザーのAPIキーを1つのソフトで使い分けて制限を回避する形は推奨されておらず、見つかった場合はより厳しい制限やキーの利用停止につながる可能性があると書かれています。枠が足りないなら、回避ではなく呼び出しの減らし方で解くのが筋です。
ここまではこちらから呼びに行く話でしたが、逆向きの仕組みもあります。Webhookです。Backlog APIには、Webhookの一覧取得、追加、取得、更新、削除の呼び出しが用意されており、設定そのものもAPIから扱えます。
取りに行く形と押してもらう形の違いは、気づくまでの時間と、無駄な呼び出しの量です。取りに行く形では、5分おきに呼んで変化を探すことになります。1日を通すと288回呼ぶ計算で、そのほとんどは何も変わっていない応答です。回数制限の枠を、待つために使っていることになります。
押してもらう形なら、変化が起きたときだけ届きます。課題が作られた、状態が変わった、コメントが付いた、といった出来事をきっかけに通知が飛ぶので、気づくまでの時間も短くなります。チャットに流したい、社内の別の仕組みに知らせたい、という用途ならこちらが向いています。
使い分けの目安は、必要なものが「出来事」か「今の全体像」かです。誰かが課題を閉じたことを知らせたいなら出来事なのでWebhook、期限切れの残件数を毎朝集計したいなら全体像なので取りに行く形になります。両方を1つの仕組みに混ぜると、どちらの経路でデータが来たのか分からなくなって保守が難しくなるので、目的ごとに分けて作るほうが後で読めます。
押してもらう形には、受け取る側を用意する手間があります。外から届くリクエストを受ける口を立て、届いた内容が本物かを確かめ、失敗したときの再送をどう扱うかを決める必要があります。社内にその口を置く場所が無い段階では、まず取りに行く形で毎朝1回動かす仕組みから始めて、頻度が足りないと分かってからWebhookへ移るのが無駄がありません。
Backlogには公式のJavaライブラリとしてBacklog4jが提供されており、そのほかにも第三者が作ったライブラリがあると案内されています。使うか使わないかの判断は、作るものの寿命で決めるのが分かりやすいです。
1回だけ動かして結果をもらえばよい調査なら、素のHTTPで十分です。curlで叩いて結果をファイルに落とし、表計算で開く。認証も引数も少ないので、ライブラリを入れる手間のほうが大きくなります。
毎日動かす仕組みなら、ライブラリの恩恵が出ます。認証の付け方、ページをまたいだ取得、失敗したときの再試行といった部分を自分で書かずに済みます。ただしライブラリが対応していない新しい呼び出しがあることもあるので、素のHTTPで書く道も残しておく作りにしておくと詰まりません。
どちらの道でも、置き場所は分けてください。APIキーをコードの中に書かず、環境変数か設定ファイルに置き、その設定ファイルはバージョン管理から外す。これは当たり前のようで、社内向けの小さな仕組みほど守られません。キーが1つ漏れると、そのユーザーが見られる範囲すべてが読めることになります。見せる範囲をどう設計するかという話は道具を選ぶ段階から関わってくるので、安全性の考え方のページにある、案件ごとに場所を分けて中身が見えないようにする組み方も併せて読む価値があります。
APIで仕組みを組む前に、土台となる契約の条件を確かめておく価値があります。回数制限の上限が無料プランと有料プランで違うと明記されているためで、プランが変われば仕組みの前提も変わります。
2026年9月27日時点の公式の料金ページでは、スタータープランが月額2,700円（税抜）で30ユーザー・5プロジェクト・ストレージ1GB、スタンダードプランが月額16,000円（税抜）でユーザー数無制限・100プロジェクト・30GB、プレミアムプランが月額27,000円（税抜）でプロジェクト数も無制限・100GB、プラチナプランが月額75,000円（税抜）で300GBとなっています。年払いを選ぶと月払いに比べて5%引きです。最大10ユーザー・1プロジェクトまで使えるフリープランも別に案内されています。
同じページに、2027年1月1日からプランが新しくなるという告知が出ています。上限や価格の前提が変わる可能性があるので、APIで仕組みを組む前に、その告知の中身を確かめておくほうが安全です。料金の数字も上限も、公式ページで今日の値を見るのが確実です。
もう1つ、機能とプランの対応も見てください。同じページの比較表では、ガントチャートはスタンダードプラン以上で使え、スタンダードプランでは表示範囲が6か月分と注記されています。プロジェクトを横断するガントチャートはプレミアムプラン以上です。工程表を全社で横断して見たいという要件があるなら、APIを組む前にそこが満たせているかを確かめてください。APIで工程を取り出して別の画面に描くという回り道をする前に、プランの段で解ける場合があります。
APIは、道具と道具の間にある人手を埋めるためのものです。だから最後に確かめたいのは、そもそも間が空いているかどうかです。
現場でよく起きているのは、課題は課題管理に、工程表は表計算に、会話はチャットにあり、3つの間を人が毎日行き来している状態です。この形でAPIを入れると、3つの間をつなぐ仕組みを自分たちで持つことになります。つないだ後は動きますが、どちらかの仕様が変わるたびに直す役が要ります。回数制限に当たらないよう気を配る役も要ります。
もう1つの道は、間そのものを減らすことです。工程表と一覧と会話が同じ場所にあれば、つなぐ必要のある区間が短くなります。どんな板が同じ仕組みの上に載るのかはできることのページに整理があり、カンバンとガントとカレンダーとリストを同じカードの仕組みで持ち替える形が説明されています。板をまたいで人手で写す作業が無ければ、その区間のAPIは要りません。
料金の形も、この判断に関わります。機能の段で料金が分かれる作りだと、工程表を横断して見るために上の段に上がる必要が出ることがあります。機能では絞らず、区切るのは人数とボードの数だけという形もあり、この場合は必要な板を使うために段を上げる話にはなりません。上限と金額の考え方は料金のページで確かめられます。
課題管理の側とボードの側で、持っているものと持っていないものは違います。Gitのリポジトリやプルリクエストまで1か所で扱うかどうかは大きな分かれ目で、そこを含めて並べたものがBacklogとの比較にあります。他の候補と横に並べて見たいときは比較の一覧から入るのが早く、導入前に出る疑問をまとめたものはよくある質問にあります。
最後に、APIで仕組みを作るときの現実的な進め方を1つ置きます。作る前に、その集計を1回だけ手で作ってみてください。手で作れた表は、機械にも作らせられます。手で作れなかった表は、たいてい必要なデータが道具の中に入っていないだけです。その場合はAPIではなく、入力の設計を直すほうが先になります。転記をなくす仕事は、書くコードの量ではなく、入力が正しく1か所に集まっているかで決まります。
APIキーです。Backlogにログインして個人設定のAPIの画面から発行し、リクエストヘッダの「Backlog-API-Key」に入れて呼びます。クエリパラメータの「apiKey」でも渡せますが、ログやURLに残るのでヘッダに入れる形を勧めます。他人の代わりにAPIを呼ぶ必要が出てからOAuth 2.0に移れば十分です。
1回で返る件数の初期値が20件だからです。引数のcountで1から100まで指定でき、それ以上はoffsetをずらして複数回呼ぶ形になります。毎日動かす集計なら、更新日で絞るupdatedSinceを付けて前日以降だけを取ると、呼び出しの回数を大きく減らせます。
読み取り・更新・検索・アイコンの4種類に分かれていて、上限は無料プランと有料プランで異なります。いま自分に適用されている値はGETで/api/v2/rateLimitを呼ぶと取れます。超えると429が返り、X-RateLimit-Resetに枠が戻る時刻が入ります。制限はAPIキー単位ではなくユーザー単位です。
3600秒、つまり1時間です。1時間を超えて動く仕組みでは、リフレッシュトークンを使ってPOSTで/api/v2/oauth2/tokenを呼び、取り直す処理が必要になります。OAuth 2.0では認証の失敗が401とWWW-Authenticateヘッダで返るので、本文だけでなくヘッダも読む作りにしてください。