Figma APIの使い方｜レート制限・トークン・Variables APIのEnterprise条件

Figma REST APIは、Figma上のデザインデータをHTTP経由で取り出すためのAPIです。ところが日本語の解説記事は「トークンを発行してファイルをGETする」までで終わっているものが多く、実務で最初に詰まる箇所――1分あたり何回叩けるのか、Variables（変数）を取得しようとしたら403が返るのはなぜか、Webhookはどの単位に張れるのか――は、たいてい書かれていません。この記事では公式ドキュメント（2026年7月14日確認）の記述に沿って、認証・主要エンドポイント・プラン別レート制限の実数・Variables REST APIの利用条件・Webhooks v2までを一続きで整理します。

まとめ

• 認証はパーソナルアクセストークンを X-Figma-Token ヘッダに載せるだけ。トークン発行時にスコープと有効期限を選ぶ方式で、必要な権限だけを付ける。
• REST APIは基本的に読み取り用。デザイン要素の作成・変更はREST APIではできず、Plugin APIの担当になる。書き込めるのはコメント・Dev resources・Variables（条件付き）などに限られる。
• レート制限は「シート種別 × エンドポイントTier × プラン」で決まる分あたり回数制限（2025年11月17日改定）。Dev/Fullシートでファイル取得（Tier 1）はStarter 10回／分、Professional 15回／分、Organization・Enterprise 20回／分。
• Variables REST APIはEnterprise組織のFullシートだけが使える。ProfessionalやOrganizationのプランでは読み取りエンドポイントすら通らず、Enterpriseでもゲストとデバイス上のDevシートは対象外。ここを知らずに設計すると手戻りが最大になる。
• Webhooks v2はteam・project・fileのいずれかに紐づけて作る。FILE_UPDATE は編集が止まってから30分以内に1回だけ発火するため、リアルタイム同期の用途には向かない。

以下、トークン発行から順に、実際に叩くときの手順と公式仕様の数値を確認していきます。

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

REST APIとPlugin APIの役割分担

Figmaには名前の似たAPIが2系統あり、混同がそのまま実装の失敗につながります。REST API（https://api.figma.com）はFigmaの外部からHTTPで叩くもので、ファイル構造のJSON取得、画像の書き出し、コメントの読み書き、Webhookの登録などを担当します。Plugin APIはFigmaアプリの内部で動くJavaScriptで、キャンバス上のノードを実際に生成・変更できます。

つまり「REST APIでレイヤーを更新する」「REST APIでコンポーネントを作る」といった操作は、公式に提供されていません。デザインデータを書き換えたいならプラグイン側に処理を置く必要があります。REST APIが書き込みを許すのは、コメント（file_comments:write）、Dev resources（file_dev_resources:write）、Webhook（webhooks:write）、そしてEnterprise限定のVariables（file_variables:write）に限られます。

デザイントークン抽出・CI連携という使いどころ

読み取り専用という制約を踏まえると、REST APIが効くのは「Figmaを正とし、そこから下流へ流す」方向の自動化です。デザインシステムの色・タイポグラフィをCSS変数やJSONへ書き出す、デザインの更新をトリガーにスクリーンショットを再生成する、レビュー用にコメントを課題管理へ転記する、といった処理が典型です。逆に「コードやスプレッドシートを正としてFigma側を書き換える」方向は、Plugin APIかFigma MCPサーバー経由になります。AIエージェントからFigmaを操作する経路についてはFigma MCPサーバーとは？料金・使い方・対応クライアントを徹底解説で扱っています。

APIトークンの発行とfile keyの取り方

X-Figma-Tokenヘッダとスコープ付きトークン

REST APIの認証はパーソナルアクセストークン（PAT）が最短です。Figmaの設定画面からトークンを発行する際、スコープと有効期限をその場で選択します。以前のような「全権限・無期限」の1本を使い回す運用ではなくなっているため、ファイル読み取りだけのスクリプトなら file_content:read だけを付けます。主なスコープは current_user:read、file_content:read、file_metadata:read、file_comments:read / file_comments:write、file_versions:read、webhooks:read / webhooks:write、そしてEnterprise限定の file_variables:read / file_variables:write です（旧 files:read は非推奨）。

発行したトークンはリクエストヘッダ X-Figma-Token に載せます。複数ユーザーに配布するアプリを作る場合はOAuthアプリを登録し、Authorization: Bearer 形式で呼び出します。OAuthのアクセストークンは expires_in が既定90日で、https://api.figma.com/v1/oauth/refresh による更新が前提です。

ファイルURLからのfile key抽出

ほぼすべてのエンドポイントが :file_key を要求します。file keyはFigmaのファイルURL https://www.figma.com/design/<file_key>/<file_name> のうち、/design/（旧形式は /file/）の直後に来るセグメントです。ブラウザのURLをそのまま貼り付けて分解すれば取れます。

import re
import requests

FIGMA_TOKEN = "figd_xxxxxxxxxxxxxxxx"  # スコープ: file_content:read
FILE_URL = "https://www.figma.com/design/abc123XYZ/Design-System"

m = re.search(r"/(?:file|design)/([A-Za-z0-9]+)", FILE_URL)
if not m:
    raise SystemExit("design file の URL ではない（FigJam は /board/、スライドは /slides/）")
file_key = m.group(1)

res = requests.get(
    f"https://api.figma.com/v1/files/{file_key}",
    headers={"X-Figma-Token": FIGMA_TOKEN},
    timeout=30,
)
res.raise_for_status()
document = res.json()["document"]
print(document["name"], len(document["children"]), "pages")

Pythonの requests でヘッダを1つ足すだけで、追加のSDKは要りません。GET /v1/files/:key は大きなファイルだとレスポンスが数十MBに膨らむため、必要なノードが分かっているなら次に挙げる nodes 版に切り替えます。

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

実務で使う頻度が高いのは次の5本です。ノードIDはFigmaでレイヤーを選択して「Copy link to selection」を実行すると、URLの node-id パラメータとして得られます。

画像書き出しの GET /v1/images/:key は、レンダリング済み画像そのものではなく一時的なダウンロードURLを返します。format は jpg / png / svg / pdf、scale は 0.01〜4 で指定でき、1枚あたり32メガピクセルが上限です。返却URLの有効期限は30日なので、長期運用するなら受け取った時点で自前のストレージへ保存します。URLをそのままDBに書いて数か月後に参照する設計は、期限切れで壊れます。

レート制限の実数と429への対処

「シート種別 × Tier × プラン」で決まる上限

Figma APIのレート制限は、よくある「1時間あたりN回」ではなくleaky bucket方式の分あたり回数制限です（現行値は2025年11月17日の改定後のもの。日本語記事でいまだに見かける「60リクエスト/分」は古い情報です）。上限値を決めるのは3つの変数です。(1) トークン所有者のシート種別（View・CollabシートはLow、Dev・FullシートはHigh）、(2) エンドポイントのTier（上の表の右列）、(3) 対象リソースが載っているプラン。ここでいうプランはトークン所有者の契約ではなく、叩く対象のファイルが属するプランです。

注目すべきはTier 1の低さと、Enterpriseに上げても上限がOrganizationから増えない点です。最上位プランでもファイル取得は毎分20回止まり。数百ファイルを横断して全ページのJSONを舐めるようなバッチは、契約を上げても成立しません。CI上でデザイントークンを抽出するなら、対象ファイルを絞り、取得結果をキャッシュして差分だけ再取得する設計が前提になります。View/Collabシートに至ってはファイル取得が月6回で、自動化には使えません。自動化用のトークンはDevシート以上のアカウントで発行するのが最低条件です（後述のVariables APIを使うならFullシートが必要）。

429応答のRetry-Afterヘッダ

上限を超えると429が返り、Retry-After ヘッダに待機すべき秒数（整数）が入ります。公式に推奨されている対処はこの値に従った再試行です。独自のバックオフを組む前に、まず Retry-After を読むこと。あわせて X-Figma-Plan-Tier（enterprise / org / pro / starter / student）と X-Figma-Rate-Limit-Type（low / high）が返るため、429の原因が「プランが低い」のか「シートがLow扱い」なのかをレスポンスヘッダだけで切り分けられます。

import time
import requests

def figma_get(url, headers, max_retry=5):
    for _ in range(max_retry):
        res = requests.get(url, headers=headers, timeout=30)
        if res.status_code != 429:
            res.raise_for_status()
            return res.json()
        wait = int(res.headers.get("Retry-After", "60"))
        print("rate limited:", res.headers.get("X-Figma-Rate-Limit-Type"), "wait", wait)
        time.sleep(wait)
    raise RuntimeError("rate limit retries exhausted")

カウントの単位も押さえておきます。PATは「ユーザー × プラン」単位、OAuthアプリは「ユーザー × プラン × アプリ」単位、組織向けのplan access tokenは「トークン × プラン」単位で数えられます。つまりチーム全員のスクリプトが同じPATを共有していると、上限を全員で食い合います。CI用途では専用アカウントのトークンを分けるか、plan access tokenを用途ごとに発行するのが安全です。

Variables REST APIはEnterprise限定という前提

存在するのは3つのエンドポイントだけ

デザイン変数（Variables）をAPIで扱う話は情報が錯綜していますが、公式に存在するエンドポイントは3本しかありません。

ネット上の解説には https://api.figma.com/v1/variables に変数を1件ずつPOSTする、という趣旨のサンプルが散見されますが、そのようなエンドポイントは公式ドキュメントに存在しません。変数の書き込みは常にファイル単位の一括操作で、variableCollections / variables / variableModes / variableModeValues の各配列をまとめて送ります。新規作成時は自分で決めた一時IDを本文内で参照させる方式（作成と値の設定を同じリクエストで完結させる）で、リクエストボディは最大4MBです。

Variables APIのプラン条件（Enterprise・Fullシート）

そしてこれが最大の落とし穴です。Variablesの3エンドポイントはいずれもEnterprise組織のFullシート限定で、読み取りのGETも例外ではありません。ProfessionalやOrganizationプランのファイルに対しては、file_variables:read スコープ付きのトークンを持っていても通らない設計です。Enterprise契約であっても、ゲストアカウントは対象外。前章で「自動化用トークンはDevシート以上」と書きましたが、Variablesを扱うならDevでは足りずFullシートが要ります。POSTはさらに対象ファイルへの編集権限も必要です。

Enterpriseでない環境でVariablesを外部へ書き出したいなら、REST APIではなくPlugin API（プラグインからローカル変数を読み、外部へPOSTする）に寄せるのが現実的な回避策になります。「まずAPIで取得できるか試す」の前に契約プランとシート種別を確認するだけで、無駄な調査を丸ごと省けます。

import requests

# 前掲のコードで取得した file_key と FIGMA_TOKEN を使う
# Enterprise 組織の Full シートのトークンでのみ 200 が返る
res = requests.get(
    f"https://api.figma.com/v1/files/{file_key}/variables/local",
    headers={"X-Figma-Token": FIGMA_TOKEN},  # スコープ: file_variables:read
    timeout=30,
)
if res.status_code == 403:
    raise SystemExit("Variables API は Enterprise + Full シート限定。プランとシートを確認する")
res.raise_for_status()
meta = res.json()["meta"]
for var in meta["variables"].values():
    print(var["name"], var["resolvedType"])

local はそのファイルで作成したローカル変数と、ファイルが参照しているリモート変数を返し、モード情報を含みます。published はライブラリとして公開された変数を返し、モードを含まない代わりに各変数へ subscribed_id が付きます。ライブラリを購読している側のファイルから変数を解決したいときは published を使います。

Webhooks v2で更新を受け取る

team・project・fileへのWebhook登録

ポーリングでファイルを叩き続けるとTier 1の上限（毎分10〜20回）をすぐ使い切ります。更新検知はWebhooks v2に寄せます。エンドポイントは POST /v2/webhooks（作成）、GET /v2/webhooks、PUT / DELETE /v2/webhooks/:webhook_id、配信履歴の GET /v2/webhooks/:webhook_id/requests です。旧来の GET /v2/teams/:team_id/webhooks は非推奨になりました。

作成時に context（team / project / file）と context_id を指定します。チーム全体ではなく特定ファイルだけを監視できるのが現行仕様です。作れる個数は次のとおりで、fileコンテキストのWebhookだけは、1ファイルあたりの3個とは別に、プラン単位の総数上限がかかります。

FILE_UPDATEの発火タイミング

受け取れるイベントは FILE_UPDATE、FILE_DELETE、FILE_VERSION_UPDATE、LIBRARY_PUBLISH、FILE_COMMENT、DEV_MODE_STATUS_UPDATE（PING は購読不可の疎通確認用）。ここで設計を誤りやすいのが FILE_UPDATE の発火タイミングで、編集操作が止まってから30分以内にまとめて1回発火します。1操作ごとに飛んでくるわけではないため、「保存した瞬間にCIを回す」用途には使えません。デザイン確定を待ってビルドを回す、という粒度で組むのが正解です。配信に失敗した場合は5分後・30分後・3時間後に再送されるので、受け口は同一イベントの重複を許容できるようにしておきます。

プランと料金からAPI利用可否を判断する

REST APIそのものは無料のStarterプランでも利用できます（レート上限は低く、Tier 1は毎分10回）。有料化が必須になるのは、Variables API（Enterprise・Fullシート）とLibrary Analytics API（Enterprise）を使う場合、そして自動化用アカウントにDev/Fullシートを割り当てる場合です。

API観点で効くのはシートの種別です。CollabやViewシートのアカウントでトークンを作ると、レート制限がLow側に落ちて実質バッチが回りません。自動化担当のアカウントには最低でもDevシートを割り当てます。価格は改定されるため、発注前に公式の料金ページで最新額を確認してください。なお、Figma Make利用時のAIクレジット消費はAPIのレート制限とは別枠の課金で、Figma Makeの料金・AIクレジットとは？プラン別の上限と消費量・使い方・エクスポートまで解説で整理しています。

よくある質問

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

REST API自体は無料のStarterプランでも呼び出せます。ただしレート制限が低く（ファイル取得はDev/Fullシートでも毎分10回）、Variables APIとLibrary Analytics APIはEnterprise限定です。さらにトークン所有者のシートがView/Collabだとファイル取得が月6回まで落ちるため、実務の自動化ではDevシート以上が事実上の前提になります。

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

分あたりの回数制限で、シート種別・エンドポイントTier・プランの3つで決まります（2025年11月17日改定）。Dev/Fullシートの場合、ファイル取得などのTier 1はStarter 10回／分、Professional 15回／分、Organization・Enterprise 20回／分。コメントやWebhookなどのTier 2は25〜100回／分です。超過すると429と Retry-After ヘッダが返ります。

Figma APIのトークンはどこで取得しますか？

Figmaの設定画面からパーソナルアクセストークンを発行します。発行時にスコープ（file_content:read など）と有効期限を選択し、取得した文字列をリクエストの X-Figma-Token ヘッダに設定します。複数ユーザー向けのアプリを配布する場合はOAuthアプリを登録し、Authorization: Bearer 形式を使います。

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

Variablesの3エンドポイントはEnterprise組織のFullシートに限定されているためです。読み取りの GET /v1/files/:file_key/variables/local も対象で、Professional・Organizationプランでは通りません。EnterpriseでもDevシートやゲストでは403になります。それ以外の環境では、Plugin APIから変数を読み出して外部へ送る方式に切り替えます。

Figma APIでデザインを更新できますか？

REST APIではできません。ノードの作成・変更はPlugin APIの領分で、REST側で書き込めるのはコメント、Dev resources、Webhook、そしてEnterprise限定のVariablesだけです。外部システムを起点にキャンバスを書き換えたい場合はプラグインかFigma MCPサーバー経由になります。

関連記事

• Figma MCPサーバーとは？料金・使い方・対応クライアントを徹底解説
• use_figmaとは？Figma MCPでAIがキャンバスに書き込む仕組みと制限
• Figma Makeの料金・AIクレジットとは？プラン別の上限と消費量・使い方・エクスポートまで解説
• Figma Motionとは｜2026年新搭載タイムラインでUIアニメーションを作る方法