Figma REST APIで取得できるのは、ファイルの中身（ページとレイヤーのJSON）、レイヤーを描いた画像、コメント、版の履歴、公開したコンポーネントとスタイル、変数、Webhookの設定です。
反対に、レイヤーを作る・動かす・色を変えるといったデザインの書き換えは、REST APIではできません。
この記事では、エンドポイントごとに返る項目と、必要なスコープ、回数制限の層を一覧にしました。
内容は、Figmaが公開しているOpenAPI仕様の v0.47.0（2026年10月30日更新）と開発者向けドキュメントで、2026年11月5日に確かめています。
取得できる情報の早見表
知りたいことから、使うエンドポイントを選べる表です。
スコープはトークンを作るときに選ぶ権限で、層（Tier）は回数制限の区分を表します。
| 知りたいこと | エンドポイント | 主に返る項目 | スコープ | 層 |
|---|---|---|---|---|
| ファイル全体のレイヤー構造 | GET /v1/files/:file_key | document（ページとレイヤーの木）、components、styles、version | file_content:read | 1 |
| 特定のレイヤーだけ | GET /v1/files/:file_key/nodes | nodes（ノードIDごとの document） | file_content:read | 1 |
| レイヤーを描いた画像 | GET /v1/images/:file_key | images（ノードID→画像のURL） | file_content:read | 1 |
| 貼り付けた画像の元データ | GET /v1/files/:file_key/images | meta.images（imageRef→画像のURL） | file_content:read | 2 |
| ファイル名・作成者・最終更新 | GET /v1/files/:file_key/meta | name、creator、last_touched_at、editorType、link_access | file_metadata:read | 3 |
| 版の履歴 | GET /v1/files/:file_key/versions | id、created_at、label、description、user | file_versions:read | 2 |
| コメント | GET /v1/files/:file_key/comments | message、client_meta、parent_id、resolved_at、reactions | file_comments:read | 2 |
| 自分のアカウント | GET /v1/me | id、handle、img_url、email | current_user:read | 3 |
| 公開したコンポーネント | GET /v1/files/:file_key/components | key、name、description、node_id、containing_frame | library_content:read | 3 |
| 公開したスタイル | GET /v1/files/:file_key/styles | key、name、style_type、node_id | library_content:read | 3 |
| フォルダーとファイルの一覧 | GET /v2/teams/:team_id/folders | フォルダーの一覧。中のファイルは別のエンドポイントで取る | folders:read | 2 |
| 変数 | GET /v1/files/:file_key/variables/local | variables、variableCollections（Enterpriseのみ） | file_variables:read | 2 |
| Dev Modeのリンク | GET /v1/files/:file_key/dev_resources | name、url、node_id | file_dev_resources:read | 2 |
| Webhookの設定 | GET /v2/webhooks | event_type、context、endpoint、status | webhooks:read | 2 |
仕様では、古いスコープ files:read も多くのエンドポイントで受け付けると書かれていますが、扱いは非推奨です。
トークンの作り方とスコープの選び方は、Figmaの個人アクセストークンの取得方法で手順をまとめました。
回数制限は「席」と「層」で決まる
REST APIの回数制限は、使う人の席（シート）の種類と、エンドポイントの層と、ファイルがあるプランの3つで決まります。
公式のRate Limitsの表を、2026年11月5日時点の内容で整理しました。
| 層 | 主なエンドポイント | 閲覧・コラボ席 | Dev・フル席（Professional／Organization／Enterprise） |
|---|---|---|---|
| Tier 1 | ファイル全体、ノード、画像の描画 | 月20回まで | 毎分10回／15回／20回 |
| Tier 2 | コメント、版の履歴、貼り付けた画像、フォルダー、変数、Webhook など | 毎分5回まで | 毎分25回／50回／100回 |
| Tier 3 | コンポーネントとスタイル、ファイルのメタ情報、ユーザー など | 毎分10回まで | 毎分50回／100回／150回 |
閲覧席やコラボ席でファイル全体を取ると月20回で止まるので、くり返し取る仕組みにはDev席かフル席のトークンが向いています。
閲覧席とコラボ席は、混み合っているときに表の回数より少なくなることがあるとも書かれています。
上限を超えたときの応答は 429 で、Retry-After に待つ秒数が入る仕組みです。
ファイル全体：GET /v1/files/:file_key
ファイルの中身をまとめて返すエンドポイントで、返り値の中心は document です。
ファイルキーは、ファイルのURLの /design/（古いURLでは /file/）の後ろに続く文字列を指します。
返る項目
| 返る項目 | 中身 |
|---|---|
name | ファイル名 |
lastModified | 最終更新の日時（UTC） |
version | 版の番号。変わったかどうかの判定に使える |
role | トークンの持ち主のこのファイルでの役割 |
editorType | figma か figjam |
thumbnailUrl | サムネイル画像のURL |
linkAccess | リンク共有の権限（inherit・view・edit・org_view・org_edit） |
document | 種類が DOCUMENT のノード。下にページ、その下にレイヤーが続く |
components・componentSets | ファイルで使っているコンポーネントのメタ情報（key、name、description など） |
styles | スタイルのメタ情報（key、name、styleType など） |
mainFileKey・branches | ブランチの情報（branch_data=true のとき） |
styles に入るのは名前と種類だけで、色や文字サイズの値は入りません。
値を知りたいときは、そのスタイルを使っているノードの fills や style を見ます。
返り値を小さくするパラメーター
| パラメーター | 使いどころ |
|---|---|
depth | 木をどこまで返すか。1ならページまで、2ならページ直下のフレームまで |
ids | 必要なノードとその親子だけを返す |
version | 過去の版の中身を取る |
geometry=paths | ベクターのパスのデータも返す |
plugin_data | プラグインが書き込んだデータも返す |
branch_data | ブランチの情報も返す |
大きなファイルをそのまま取ると返り値が重くなるため、最初は depth=1 でページの一覧だけを取るのが扱いやすい方法です。
特定のレイヤー：GET /v1/files/:file_key/nodes
ids にノードIDをカンマ区切りで渡すと、そのノードだけを返します。
返り値の nodes は、ノードIDごとに document（そのノード）と、使っているコンポーネントやスタイルのメタ情報を持つ形です。
ノードIDは、レイヤーのリンクの node-id= の後ろにあり、URLでは 1-2、APIでは 1:2 と書きます。
選んだレイヤーのIDをまとめて控えたいときは、選択レイヤーのURLを一括取得するプラグインが使えます。
ノードに入っている主な項目
ノードの項目は種類によって違いますが、多くのノードに共通するのは次の項目です。
| 分類 | 項目 | 中身 |
|---|---|---|
| 識別 | id・name・type・visible・locked | ID、レイヤー名、種類（FRAME・TEXT・INSTANCE など）、表示と固定 |
| 位置と大きさ | absoluteBoundingBox・absoluteRenderBounds・size・relativeTransform・rotation | キャンバス上の座標と寸法、影を含む描画範囲、親からの変形 |
| 制約 | constraints | 親フレームに対する追従のしかた |
| オートレイアウトの子 | layoutPositioning・layoutSizingHorizontal・layoutSizingVertical・layoutGrow | 絶対配置か、Fixed・Hug・Fill のどれか |
| 塗りと線 | fills・strokes・strokeWeight・strokeAlign・strokeDashes | 単色・グラデーション・画像の塗り、線の太さと位置、破線 |
| 効果と合成 | effects・opacity・blendMode | 影・ぼかし、不透明度、描画モード |
| マスク | isMask・maskType | マスクかどうかと、その種類 |
| 変数 | boundVariables・explicitVariableModes | 項目に割り当てた変数のID、明示したモード |
| 書き出し | exportSettings | レイヤーに登録した書き出し設定 |
| プロトタイプ | interactions | クリックなどの操作と遷移先 |
| プラグイン | pluginData・sharedPluginData | plugin_data を指定したときだけ入る |
テキスト（TEXT）
| 項目 | 中身 |
|---|---|
characters | 文字列そのもの |
style | フォント名・太さ・サイズ・行送り・字間・揃え・自動リサイズ・リンクなどの書式（TypeStyle） |
characterStyleOverrides・styleOverrideTable | 一部の文字だけ書式を変えたときの、文字ごとの上書き |
lineTypes・lineIndentations | 行ごとの箇条書きの種類と字下げ |
styles | 使っているテキストスタイルや塗りスタイルのID |
PostScript名（fontPostScriptName）は空（null）で返ることがあるので、フォントの判定には fontFamily と fontWeight も合わせて見ます。
文字の色が入るのは fills です。
フレーム（FRAME）
| 項目 | 中身 |
|---|---|
layoutMode | NONE・HORIZONTAL・VERTICAL・GRID。オートレイアウトの向き |
itemSpacing・counterAxisSpacing | 子どうしの間隔と、折り返した行の間隔 |
paddingLeft ほか4方向 | 内側の余白 |
primaryAxisAlignItems・counterAxisAlignItems | 主軸と交差軸の揃え |
layoutWrap | 折り返すかどうか |
gridRowCount・gridColumnCount など | グリッドレイアウトの行と列 |
clipsContent | はみ出した部分を隠すか |
cornerRadius・rectangleCornerRadii・cornerSmoothing | 角丸と、角ごとの値、スムージング |
layoutGrids | レイアウトグリッド |
devStatus | Dev Modeの「開発の準備完了」などの状態 |
オートレイアウトの値はCSSのflexにほぼ対応するので、コードに起こすときの手がかりになります。
インスタンス（INSTANCE）
| 項目 | 中身 |
|---|---|
componentId | 元になったコンポーネントのID |
componentProperties | コンポーネントプロパティの名前と値（バリアントの選択もここに入る） |
overrides | このインスタンスで直接上書きした項目の一覧 |
exposedInstances・isExposedInstance | 入れ子のインスタンスを外に出しているかどうか |
インスタンスの fills や characters は、上書きを反映した後の値です。
元のコンポーネントとの違いを見たいときは、componentId で元のノードを取り、項目を比べます。
画像：GET /v1/images と /files/:file_key/images
名前は似ていますが、2つは返すものが違います。
| エンドポイント | 返すもの | 条件 |
|---|---|---|
GET /v1/images/:file_key | 指定したノードを描いた画像のURL | 形式は jpg・png・svg・pdf、倍率は 0.01〜4。URLは30日で切れる |
GET /v1/files/:file_key/images | ファイルに貼り付けた画像そのもののURL | imageRef ごとに返る。URLは長くても14日で切れる |
描画に失敗したノードの値は、URLではなく null です。
3,200万画素を超える画像は縮小されます。
画像のURLには期限があるため、記事やツールに直接貼ると、しばらくして表示されなくなる点に注意が必要です。
SVGで書き出すときは、文字をパスにするか（svg_outline_text）、id属性を付けるかも選べます。
Pythonでまとめて保存する手順は、Figma REST APIで画像を一括書き出しする方法で書きました。
版の履歴・コメント・ユーザー
版の履歴
GET /v1/files/:file_key/versions は、ファイルの保存された版の一覧を返します。
1回に返る数は page_size で決まり、初期値は30件、上限は50件です。
続きは before に版のIDを渡して取ります。
返った版のIDを GET /v1/files の version に渡せば、その時点の中身が取れる仕組みです。
コメント
| 操作 | エンドポイント | 主な項目 |
|---|---|---|
| 取得 | GET /v1/files/:file_key/comments | message、client_meta（位置）、parent_id（返信先）、resolved_at、reactions。as_md=true で本文をマークダウンで返す |
| 投稿 | POST /v1/files/:file_key/comments | message は必須。返信は comment_id、位置は client_meta で指定する |
| 削除 | DELETE /v1/files/:file_key/comments/:comment_id | コメントを消す。消せるのは書いた本人だけ |
| リアクション | …/comments/:comment_id/reactions | 取得・追加・削除 |
返信に返信することはできず、返信先は最初のコメントに限られます。
コメントを表にする方法はFigmaのコメントをREST APIで取得・CSV出力する方法、スプレッドシートに出す方法はFigmaの情報をGoogleスプレッドシートに出力する方法で紹介しました。
ユーザー
GET /v1/me は、トークンの持ち主の id、handle（表示名）、img_url（アイコン）、email を返します。
トークンが正しく動いているかを確かめる、最初の1回に向いたエンドポイントです。
コンポーネント・スタイル（ライブラリ）
ライブラリとして公開したコンポーネントやスタイルは、ファイル単位・チーム単位・1つずつの3通りで取れます。
| 単位 | コンポーネント | スタイル |
|---|---|---|
| ファイル | GET /v1/files/:file_key/components | GET /v1/files/:file_key/styles |
| チーム | GET /v1/teams/:team_id/components | GET /v1/teams/:team_id/styles |
| 1つ | GET /v1/components/:key | GET /v1/styles/:key |
返るのは key、name、description、node_id、thumbnail_url、作成と更新の日時、containing_frame（置かれているフレーム）などのメタ情報です。
コンポーネントセット（バリアントのまとまり）も、同じ形の component_sets で取れます。
公開していないコンポーネントはここには出ないため、GET /v1/files の components が確認先です。
チーム・フォルダー・ファイルの一覧
以前の「プロジェクト」は今は「フォルダー」と呼ばれ、APIも v2 のフォルダー用に移りました。
| 取りたいもの | 今のエンドポイント | 以前のエンドポイント（非推奨） |
|---|---|---|
| チームの最上位のフォルダー | GET /v2/teams/:team_id/folders | GET /v1/teams/:team_id/projects |
| フォルダーの中のフォルダー | GET /v2/folders/:folder_id/folders | なし |
| フォルダーの中のファイル | GET /v2/folders/:folder_id/files | GET /v1/projects/:project_id/files |
| フォルダーの情報 | GET /v2/folders/:folder_id/meta | GET /v1/projects/:project_id/meta |
チームIDはAPIからは取れません。
ブラウザでチームのページを開き、URLの /team/ の後ろにある数字を使います。
変数・Dev Modeのリンク・管理用のAPI
| 機能 | エンドポイント | 使える条件 |
|---|---|---|
| ローカル変数 | GET /v1/files/:file_key/variables/local | Enterprise の組織のフルメンバー。モードの値も返る |
| 公開した変数 | GET /v1/files/:file_key/variables/published | 同上。モードの値は返らない |
| 変数の作成・変更・削除 | POST /v1/files/:file_key/variables | 同上 |
| Dev Modeのリンク | GET /v1/files/:file_key/dev_resources | ノードに付けた外部リンク（name・url・node_id）。追加・更新・削除もできる |
| ライブラリの利用状況 | GET /v1/analytics/libraries/:file_key/… | コンポーネント・スタイル・変数ごとの使用数と操作の記録 |
| 監査ログなど | GET /v1/activity_logs ほか | 組織の管理者向け。プランのアクセストークンを使う |
変数のAPIは Enterprise 以外のプランでは使えないため、その場合は Figma の書き出し機能かプラグインで取り出すことになります。
変数をJSONにする方法の比べ方は、Figma VariablesをJSONへ書き出す方法にまとめました。
Webhook（V2）
Webhookは、ファイルの更新やコメントがあったときに、指定したURLへ通知を送る仕組みです。
| 操作 | エンドポイント |
|---|---|
| 作成 | POST /v2/webhooks |
| 一覧 | GET /v2/webhooks |
| 1件の取得・更新・削除 | GET・PUT・DELETE /v2/webhooks/:webhook_id |
| 送った記録 | GET /v2/webhooks/:webhook_id/requests |
作成するときは、event_type・context・context_id・endpoint・passcode の5つが必須です。
context はチーム（TEAM）、フォルダー（PROJECT）、ファイル（FILE）から選びます。
| イベント | 通知されるとき |
|---|---|
FILE_UPDATE | ファイルが更新されたとき |
FILE_VERSION_UPDATE | 版が保存されたとき |
FILE_DELETE | ファイルが削除されたとき |
FILE_COMMENT | コメントが付いたとき |
LIBRARY_PUBLISH | ライブラリが公開されたとき |
DEV_MODE_STATUS_UPDATE | Dev Modeの状態が変わったとき |
PING | 作成した直後の確認 |
passcode は署名ではなく、通知の本文にそのまま入って返ってくる合言葉です。
受け取る側で値を照らし合わせ、自分が作ったWebhookからの通知かを確かめます。
作成した直後に届くのが PING です。
止めた状態で作りたいときは、status を PAUSED にして作ります。
受け取る側の作り方は、Figma Webhooks V2の使い方で試しました。
REST APIでできないこと
REST APIで書き込めるのは、コメント、リアクション、変数、Dev Modeのリンク、Webhookと、Enterprise向けの管理操作に限られます。
レイヤーを作る、動かす、色や文字を変えるといった操作は、エンドポイントがありません。
デザインを書き換えたいときは、Figmaの中で動くPlugin APIを使います。
2つのAPIの違いはFigma REST APIとPlugin APIの違い、プラグインの作り方はFigmaプラグイン開発の始め方で説明しました。
AIのエージェントからデザインを読ませたいときは、Figma MCPの設定方法も選択肢です。
エラーが返るときの原因と対処
トークンを付けずに、実際に要求を送ってみました（2026年11月5日）。
| 送った要求 | 返った結果 |
|---|---|
トークンなしで GET /v1/me | 401 {"status":401,"err":"Missing credentials"} |
トークンなしで GET /v1/files/… | 403 {"status":403,"err":"Invalid token"} |
でたらめなトークンで GET /v1/me | 401 {"status":401,"err":"Invalid token"} |
同じ「トークンが無い」状態でも、エンドポイントによって 401 と 403 に分かれました。
403 や 401 が返ったら、まずヘッダー名が X-Figma-Token になっているか、トークンを貼るときに空白が入っていないかを見ます。
トークンが正しいのに 403 になるときは、スコープが足りないか、そのファイルを開く権限がない場合が考えられます。
429 が返ったときの対処は、Retry-After の秒数だけ待ってから送り直すことです。
手元で試すときの最小の形は次のとおりです。
curl -H "X-Figma-Token: <個人アクセストークン>" \
"https://api.figma.com/v1/files/<ファイルキー>?depth=1"トークンを入れて実際のファイルを取る部分は、この記事では試していません。
項目名と条件は、公式の仕様とドキュメントの記載にもとづいています。
まとめ
- REST APIで取れるのは、ファイルの中身、画像、版の履歴、コメント、ライブラリ、変数、Webhookです。
- デザインの書き換えはできず、Plugin APIの役目になります。
- ファイル全体・ノード・画像はTier 1で、閲覧席とコラボ席では月20回までしか取れません。
- スタイルの値、チームID、未公開のコンポーネントは、それぞれ別の場所から取ります。
- 変数のAPIはEnterpriseの組織のフルメンバーだけが使えます。
エンドポイントは仕様の更新で増えたり非推奨になったりするので、作る前にREST APIの変更履歴も見ておくと安心です。