Figma APIの使い方｜APIキー発行・レート制限の実数・Variables REST APIの条件【2026年10月】

Figma REST APIは、Figmaのファイルやコメント、変数をHTTPで読み書きするためのAPIです。使い始めは簡単で、APIキー（個人アクセストークン）をヘッダに載せてGETするだけです。つまずくのはその先で、「Proプランなのに429が返り、Retry-Afterが数日を指している」「Variablesを取ろうとすると403になる」といった問題では、まずプラン、シート、ファイルの所在、トークンのスコープを確認します。この記事は、2026年10月16日に公式ドキュメントを取得し直した内容をもとに、認証、主要エンドポイント、レート制限表の正しい読み方、429の切り分け、Variables REST APIの条件、Webhooks v2を順に整理したものです。

まとめ

• APIキーにあたるのは個人アクセストークン（PAT）で、X-Figma-Token ヘッダに載せて送ります。有効期限は最長90日で、無期限のトークンは2025年4月以降作れません。組織の自動化には、2026年7月に一般提供が始まったプランアクセストークン（Organization・Enterprise限定、最長365日）が向いています。
• REST APIでデザインのノードは作れません。書き込めるのはコメント、Dev resources、Webhook、Variables（Enterpriseのみ）などに限られ、キャンバスを編集するならPlugin APIかFigma MCPサーバーを使います。
• レート制限は「シート種別・エンドポイントのTier・リソースが置かれたプラン」の3つで決まります。Dev・Fullシートの分単位の上限はProfessional・Organization・Enterpriseの3列だけで、ファイル取得（Tier 1）は10・15・20回／分です。Starterプランのファイル・ノード・画像を取得するTier 1は、シート種別にかかわらず月単位の上限になります。
• 429のヘッダが X-Figma-Rate-Limit-Type: low なのに自分がFullシートなら、対象ファイルが有料チームの外（Starter側や移動前の下書き）にある可能性が高いです。Retry-Afterが数日を指す例も報告されているので、長い待機は眠らずに止める実装にします。
• Variables REST APIはEnterpriseプラン専用です。書き込み（POST）はFullシートか管理者で、かつファイルの編集権限が必要です。それ以外のプランではPlugin APIで変数を書き出します。

Figma REST APIでできること・できないこと

REST APIは読み取りが中心です。ファイルのJSON（ノードツリー）、ノード単位の取得、画像の書き出し、コンポーネントとスタイル、バージョン履歴、コメントを取れます。FigJamのボードも同じ GET /v1/files/:key で取得でき、応答の editorType で種別を見分けます。

書き込みは限られます。スコープ一覧で :write が付いているのは、コメント（file_comments:write）、Dev resources、Webhook、変数（file_variables:write）の4系統だけです。フレームを置く、テキストを書き換えるといった操作はREST APIにはありません。

AIコーディングツールからFigmaを扱うなら、対応クライアントではFigma MCPサーバーを使うと独自のREST API連携を実装せずに済み、キャンバスへの書き込みはuse_figmaが担います。デザインからReactコードを起こす経路の比較はFigmaをReactに変換する方法で整理しています。

APIキー（アクセストークン）の発行とfile keyの取得

認証方式は3つあります。自分のスクリプトならPAT、組織のCI/CDならプランアクセストークン、他のユーザーの代わりに動くアプリならOAuthアプリ、という使い分けが公式の認証ガイドの推奨です。

個人アクセストークンの発行手順とスコープ

公式の手順では、ファイルブラウザ左上のアカウントメニューから「Settings」を開き、「Security」タブの「Personal access tokens」で「Generate new token」を押します。ここで有効期限とスコープを選び、生成されたトークンはその場でしか表示されません。最終使用日時は同じ画面で確認でき、失効は即時に効きます。

有効期限は2025年4月28日の変更で最長90日になり、無期限のトークンは作れなくなりました。CIに設定したPATは、発行時に選んだ有効期限（最長90日）が来る前に更新する前提で、更新日をカレンダーに入れておくか、組織のプランならプランアクセストークンへ移します。

スコープは必要な分だけ付けます。ファイルの中身を読むだけなら file_content:read で足ります。files:read はファイル・フォルダ・コメント・Webhookまでまとめて読める広い権限で、2025年4月から非推奨です。2026年8月にはフォルダ用の folders:read と folder_metadata:read が加わり、旧来の projects:read も非推奨になりました。

プランアクセストークン（2026年7月一般提供）

プランアクセストークンは2026年7月23日に一般提供が始まった方式で、個人のアカウントではなくOrganizationまたはEnterpriseのプランに紐づきます。発行は管理者が figma.com/developers/tokens から行い、2段階認証（SSO必須の組織を除く）が前提です。対象をファイル・フォルダ・チーム単位で絞れ、有効期限は最長365日です。

注意点は使えないエンドポイントがあることです。公式ページは、file_variables:write・file_comments:write・file_code_connect:write を要するエンドポイントと、/v1/me・/v1/oembed を対象外としています。つまり変数の一括更新やコメント投稿をCIから行うなら、今もPATかOAuthアプリが必要です。

OAuthアプリを使う場面

他のFigmaユーザーの権限で動く外部サービスを作るならOAuthアプリです。2025年9月以降は公開フローが新しくなり、公開アプリはFigmaの審査を通す必要があります。チームや組織の中だけで使う非公開アプリは審査不要です。トークンの更新先は2025年5月に https://api.figma.com/v1/oauth/token へ変わり、旧 /v1/oauth/refresh は当面動くものの移行が推奨されています。

file keyとnode idの取り方

file keyはファイルURLの /design/（FigJamなら /board/）の直後の文字列です。ノードを選択して「リンクをコピー」すると ?node-id=12-34 が付き、APIに渡すときはハイフンをコロンに直して 12:34 にします。ブランチのURLでは /branch/ の後ろがブランチのキーで、Variablesの公開済み取得はブランチではなく元ファイルのキーを渡す必要があります。

主要エンドポイントと画像書き出し

最初の疎通確認は次のcurlで十分です。ベースURLは https://api.figma.com で、HTTPは2024年12月9日からリダイレクトされず403になります。

export FIGMA_TOKEN=figd_xxxxxxxxxxxxxxxx
# ページ直下のフレームまでに絞ってファイルを取得する
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/FILE_KEY?depth=2"
# 複数ノードをPNGで一括書き出し（1リクエストにまとめる）
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/images/FILE_KEY?ids=1:2,1:3&format=png&scale=2"

大きなファイルを丸ごと取ると、400で「Request too large」が返ります。depth と ids で範囲を絞るのが公式の推奨です。更新日時や作成者だけを見たいなら、本文を返さない GET /v1/files/:key/meta を使うとTier 3の枠で済み、Tier 1を節約できます。

画像書き出しの format はjpg・png・svg・pdf、scale は0.01〜4です。返るURLは30日で失効し、32メガピクセルを超える画像は縮小されます。画像の塗り（GET /v1/files/:key/images）のURLはさらに短く、14日以内に失効します。URLをDBに保存して後で使う設計は、期限切れで壊れます。

2026年8月10日には、ネストしたフォルダに対応した GET /v2/teams/:team_id/folders などのフォルダ系エンドポイントが追加され、/v1/teams/:team_id/projects と /v1/projects/:project_id/files は非推奨になりました。チーム配下のファイルを一覧するスクリプトは、対象プランでネストしたフォルダが有効になっていることを確認してからv2を使います。

Figma APIのレート制限（2026年10月時点の上限表）

レート制限は2025年11月17日に改定された方式が続いています。上限を決めるのは、リクエストしたユーザーのシート種別、エンドポイントのTier、そしてリソースが置かれたプランの3つです。下の表は公式のRate Limitsページを2026年10月16日に取得し、セルの結合まで分解して読んだものです。

Tier 1はファイル・ノード・画像の取得、Tier 2はコメント・Dev resources・画像の塗り・フォルダとプロジェクトの一覧・Variablesの読み取り・バージョン履歴・Webhook、Tier 3はコンポーネントとスタイル・ファイルのメタデータ・Library Analytics・Variablesの書き込みなどです。View・Collabの値は「まで」で、混雑時はさらに下がると明記されています。

Starter列の結合セルとTier別上限の読み方

この表で最も読み違えやすいのがStarter列です。公式ページのHTMLでは、StarterのView・Collabのセルに rowspan="2" が付いており、Dev・Fullの行にはProfessional・Organization・Enterpriseの3セルしかありません。つまりStarterのファイル・ノード・画像を取得するTier 1には、Fullシートでも月単位の上限がかかります。表をテキストに崩すと「10／15／20」が左に詰まり、「Starterは10回／分」と読めてしまいます。検索エンジンのAI要約がまさにこの読み方を返すことがあり、当記事の2026年7月版も同じ誤りをしていました（今回訂正）。

公式の本文も同じ構造を説明しています。「Starterプランのファイルの中身をPATで取得すると、別のプランでFullシートを持っていても、そのファイルへのリクエストは月6回までに制限される」という例です。上限は「誰が叩くか」より「ファイルがどこにあるか」で決まります。

Tier 1の月間上限に関する公式資料の不一致

2026年10月時点で、View・CollabのTier 1の値は資料によって違います。

• 開発者ドキュメントの表：全プラン「月20回まで」。Internet Archiveの保存版では2026年6月16日版まで「月6回まで」で、9月30日版で20回に変わっていました。
• ヘルプセンターの「What if I’m rate-limited?」（2026年10月11日更新）：Starterは「月20回まで」、Professional・Organization・Enterpriseは「月6回まで」。
• 両ページの本文の例：Starterのファイルは「月6回まで」。

変更の告知はREST APIの変更履歴に載っていません。View・Collab向けツールのTier 1呼び出しは月6回以内を保守的な目安とし、それ未満でも429が返る前提で設計してください。月20回を前提にした設計では、実際の上限がそれより低い場合に予定した処理を完了できなくなります。

認証方式別のレート制限の集計単位

数え方は認証方式で変わります。PATは発行したユーザー×プラン単位なので、同僚5人が同じPATを埋め込んだスクリプトを同時に回すと、1人分の枠を5人で消費します。OAuthアプリはユーザー×プラン×アプリ単位で、同じユーザーでもアプリAとアプリBは別枠です。プランアクセストークンはトークン×プラン単位です。共有スクリプトの429が頻発するなら、まず「1本のPATを全員で使っていないか」を確認します。

429エラーの原因の切り分けと再試行

429が返ったら、再試行の前にヘッダを読みます。公式が定める応答ヘッダは4つです。

Fullシートなのにlowが返るとき

X-Figma-Rate-Limit-Type: low は、FigmaがあなたをView・Collab扱いで数えているという意味です。自分がFullシートでもこうなる典型は、ファイルが有料チームの外にあるケースです。Figmaフォーラムの報告（2026年2月）では、ProfessionalのFullシートで画像書き出しを叩いて X-Figma-Plan-Tier: pro・low・Retry-After: 396749（約4.6日）が返りました。サポートは「ファイルがアップグレードしたチームに無いことが最も多い原因」と回答し、別の報告者は下書きに取り込んだファイルを別の場所へ移したら無料側の配下に入っていたと突き止めています。

確認の順番は、(1) 対象ファイルがどのチーム・プランに属するか、(2) PATを発行したアカウントがそのプランでFullかDevか、(3) 同じPATを他の人やジョブが使っていないか、です。

Retry-Afterに従う再試行と長時間待機の停止

公式のサンプルはRetry-Afterの秒数だけ待って再送する形ですが、上の例のように4日以上を指すことがあります。CIのジョブが4日間眠っても得はないので、しきい値を超えたら例外で止めて通知する方が扱いやすくなります。次のPythonは、ローカルに立てた模擬サーバー（2回だけ429を返し、別パスでは Retry-After: 396749 を返す）で動作を確認したものです。

import os
import time
import requests

API = os.environ.get("FIGMA_API", "https://api.figma.com")
TOKEN = os.environ["FIGMA_TOKEN"]
MAX_WAIT = 120  # これを超える Retry-After は待たずに止める（秒）


class FigmaRateLimited(Exception):
    pass


def figma_get(path, params=None, max_retries=5):
    for attempt in range(max_retries + 1):
        r = requests.get(f"{API}{path}", params=params,
                         headers={"X-Figma-Token": TOKEN}, timeout=60)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        wait = int(r.headers.get("Retry-After", "60"))
        info = (f"tier={r.headers.get('X-Figma-Plan-Tier')} "
                f"type={r.headers.get('X-Figma-Rate-Limit-Type')} wait={wait}s")
        if wait > MAX_WAIT or attempt == max_retries:
            raise FigmaRateLimited(info)
        print(f"429 {info} -> {wait}秒待って再試行")
        time.sleep(wait)


print(figma_get("/v1/files/FILE_KEY", params={"depth": 2}))

pip install requests のうえ環境変数 FIGMA_TOKEN にPATを入れて実行します。下の出力は、同じ関数を模擬サーバーに向けて（FIGMA_API を差し替えて）実行したときのものです。

429 tier=org type=high wait=1s -> 1秒待って再試行
429 tier=org type=high wait=1s -> 1秒待って再試行
{'name': 'demo', 'lastModified': '2026-10-16T00:00:00Z'}
停止: tier=pro type=low wait=396749s

そもそも429を出さない工夫は、画像を1ノードずつではなく ids にまとめて1回で書き出すこと、取得結果をキャッシュして画面を開くたびに叩かないこと、変更検知をポーリングでなくWebhookに任せることの3点に集約されます。

401と403の見分け方

認証エラーの形はエンドポイントで揃っていません。2026年10月16日に無効なトークンで叩いた結果は次のとおりです。

GET https://api.figma.com/v1/me
-> 401 {"status":401,"err":"Invalid token"}
GET https://api.figma.com/v1/files/AbCdEf123/variables/local
-> 403 {"status":403,"error":true,"message":"Invalid token"}
GET http://api.figma.com/v1/me
-> 403 Forbidden（HTMLの応答）

同じ「トークンが無効」でも、ステータスは401と403、本文のキーは err と message に分かれます。エラー処理を status == 401 だけで書くと、Variables系の失効を「権限不足」と誤判定します。両方のキーを見て、403のときは本文の文言で失効か権限不足かを分けてください。

Variables REST APIの条件とエンドポイント

Variables REST APIは、デザイントークンをFigmaとコードの間で同期するためのAPIで、エンドポイントは3本だけです。

GET  /v1/files/:file_key/variables/local      # ローカル変数とファイルが使うリモート変数
GET  /v1/files/:file_key/variables/published  # 公開済みの変数（モードは返らない）
POST /v1/files/:file_key/variables            # コレクション・モード・変数の一括作成・更新・削除

Enterpriseプラン専用という条件

公式の条件表は次のとおりで、GETもPOSTもEnterpriseプランが必須です。ゲストは使えません。

ただし同じページの冒頭文は「Fullシートが必要」と書いており、GETの条件表と食い違っています。読み取り専用のジョブをDevシートのアカウントで組む前に、実際に1回叩いて確かめてください。条件を満たさないときの403の本文は「Limited by Figma plan」「Incorrect account type」「Invalid scope」のいずれかで、どの条件で落ちたかが分かります。

Enterprise以外のプランでは、GET /v1/files/:key の応答に boundVariables として変数のIDは出ますが、値までは取れません。値が必要ならPlugin APIで書き出します。デザイントークンの設計そのものはデザインシステムの解説を参照してください。

Variables POSTの上限と一時IDを使うJSON例

POSTは variableCollections・variableModes・variables・variableModeValues の4配列をこの順に適用し、全体が1つのトランザクションです。1つでも検証に失敗すると400が返り、何も保存されません。制約は本文4MB以下、1コレクションあたりモード40個・変数5,000個までです。リモート（他ファイルから参照している）変数は更新できず、更新した変数を他のファイルで使うにはFigma側で公開し直す必要があります。

新しく作るオブジェクトには一時IDを付けて、同じリクエスト内で参照できます。

{
  "variableCollections": [
    { "action": "CREATE", "id": "tmp_col", "name": "Color", "initialModeId": "tmp_light" }
  ],
  "variableModes": [
    { "action": "UPDATE", "id": "tmp_light", "name": "Light", "variableCollectionId": "tmp_col" }
  ],
  "variables": [
    { "action": "CREATE", "id": "tmp_primary", "name": "brand/primary",
      "variableCollectionId": "tmp_col", "resolvedType": "COLOR" }
  ],
  "variableModeValues": [
    { "variableId": "tmp_primary", "modeId": "tmp_light",
      "value": { "r": 0.13, "g": 0.4, "b": 0.93, "a": 1 } }
  ]
}

応答の tempIdToRealId に一時IDと実IDの対応が返ります。2025年11月には既存コレクションを親にして上書き値だけを持つ拡張コレクション（parentVariableCollectionId）、2026年9月17日には色と不透明度を別々に指定できる VariableComposedColor が加わりました。

Webhooks v2による更新通知の受信

ファイルの更新をポーリングで追うと、Tier 1の枠をすぐに使い切ります。変更検知はWebhooks v2に任せます。管理画面は無く、作成・変更・削除はすべて /v2/webhooks のAPIで行います。

登録単位ごとの上限と作成できる人

file単位のWebhookには、プラン全体での総数上限もあります（Professional 150個、Organization 300個、Enterprise 600個）。team単位のWebhookは、招待制フォルダ内のファイルについては通知しません。フォルダは以前「プロジェクト」と呼ばれていたため、contextの値は今も project です。

FILE_UPDATEの発火タイミングと検証

FILE_UPDATE は編集が止まってから30分以内に1回発火します。保存のたびに飛ぶわけではないので、リアルタイム同期には使えません。リリース作業の合図にしたいなら、名前付きバージョンを作ったときに飛ぶ FILE_VERSION_UPDATE や、ライブラリ公開の LIBRARY_PUBLISH の方が意図どおりに動きます。

作成時に指定した passcode（100文字まで）が毎回のペイロードに入るので、受信側で照合し、一致しなければ400を返すのが公式の推奨です。400を返すとそのWebhookは即時に停止します。それ以外の送信失敗（200以外の応答やタイムアウト）では、初回失敗の5分後、2回目の失敗の30分後、3回目の失敗の3時間後に再送されます。直近7日間の送受信は GET /v2/webhooks/:webhook_id/requests で確認できます。

プランごとにREST APIでできること

REST API自体に利用料はありません。ただし、使える機能と上限はプランとシートで決まります。

判断の目安は単純です。社内ツールでファイルを定期取得するなら、対象ファイルをProfessional以上のチームに置き、PATを発行する人にFullかDevのシートを割り当てます。デザイントークンの同期を自動化したいのにEnterpriseでないなら、Variables REST APIを待たずにPlugin APIで書き出す構成を選ぶ方が早く終わります。FigmaとCIや社内システムをAPIでつなぐ設計を外部に任せたい場合は、API開発・システム連携の支援でも相談を受けています。

よくある質問

Figma APIは無料で使えますか？

REST API自体は無料で、Starterプランでも使えます。ただしStarterでのファイル・ノード・画像取得（Tier 1）には月単位の上限があり、Variables REST APIやプランアクセストークンは有料プラン（VariablesはEnterprise）に限られます。

Figma APIのレート制限はどのくらいですか？

Dev・Fullシートでファイルを取得するTier 1は、Professional 10回／分、Organization 15回／分、Enterprise 20回／分です。View・CollabシートとStarterのファイルは月単位で、資料によって月6回と月20回の表記があります。

Figma APIのキー（アクセストークン）はどこで発行しますか？

アカウントメニューの「Settings」から「Security」タブを開き、「Personal access tokens」で発行します。有効期限は最長90日で、トークンは発行時に一度だけ表示されます。

Figma Variables REST APIで403になるのはなぜですか？

多くはプランの条件です。Variables REST APIはEnterpriseプラン専用で、読み取りにはトークンの file_variables:read スコープ、書き込みにはFullシートまたは管理者のアカウントと、ファイルの編集権限、file_variables:write スコープが必要です。トークンが失効していても403が返ります。

Figma APIでデザインを編集できますか？

REST APIではノードの作成や変更はできません。書き込めるのはコメント、Dev resources、Webhook、Variables（Enterprise）です。キャンバスの編集はPlugin APIかFigma MCPサーバーを使います。

関連記事

• Figma MCPサーバーとは｜料金・レート制限・対応クライアント17種と使い方【2026年9月時点】
• use_figmaとは？Figma MCPでAIがキャンバスに書き込む仕組みと使い方・制限
• FigmaをReactに変換する4つの方法｜HTML書き出しの可否とMCP・Figma Make・エージェント・Locofyの使い分け【2026年10月】
• Figma Code Connectの使い方｜UIとCLIの始め方とDev Mode表示・CLI v2移行
• デザインシステムとは？構成要素と作り方、ガイドライン・スタイルガイドとの違い