登録済み Figma ファイルの一覧取得

メソッド

この API は REST の方法論に従います。

HTTP メソッド

GET: プロジェクトに登録された Figma ファイルを一覧します。

この一覧がファイル全体の resync のスコープを決めます — sweep はこれらのファイルのみを走査します。また、どのファイルが既にコンポーネントライブラリを同期済みかをプラグインに伝えます。

URI に wf2des セグメントが無い 点に注意してください。ファイル登録は実行単位ではなくプロジェクト単位の事実です。

命名規則

レスポンスは内部の wf2des-api データプレーンから 逐語でプロキシ されるため、フィールドは snake_case です。

リクエストとレスポンス

ヘッダー

リクエストヘッダー

Authorization
Accept
Accept-language

レスポンスヘッダー

Content-Type

Figma ファイルの一覧

URI

GET /api/v1/organizations/{organization_id}/projects/{project_id}/figma-files

パスパラメータ

名前	型	必須	説明
organization_id	integer	必須	組織 ID
project_id	integer	必須	プロジェクト ID

レスポンス

レスポンスは JSON です（HTTP ステータス: 200 OK）。

{
  "project_id": 7,
  "organization_id": 1,
  "items": [
    {
      "figma_file_key": "abc123XYZ",
      "role": "component_library",
      "config_url": null,
      "components_synced_at": "2026-08-01T09:15:00Z"
    }
  ]
}

レスポンスフィールド

名前	型	説明
project_id	integer	一覧が属するプロジェクト。
organization_id	integer	読み取りが組織にスコープされた場合のみ存在する。
items	object[]	登録済みファイルごとに 1 件。

item フィールド

名前	型	説明
figma_file_key	string	Figma ファイルキー（逐語）。`(organization_id, project_id)` ごとに一意。
role	string \| null	ファイルの登録種別 — コンポーネントライブラリ、ガイドラインファイルなど。
config_url	string \| null	ファイルに対する任意の設定ポインタ。
components_synced_at	string \| null	このファイルで最後にコンポーネント sweep が完了した時刻。未実施の場合は `null`。

items が空配列であることは正常な状態でありエラーではありません — プロジェクトにまだ何も登録されておらず、ファイル全体の resync も走査対象を持たないことを意味します。

認証

認証は Amazon Cognito が発行する JSON Web Token（JWT）で行われます。加えて、呼び出し元はプロジェクトへのアクセス権を保持している必要があります。

エラーハンドリング

説明	ステータスコード	ステータス名
認証情報の欠落	401	Unauthorized
権限不足	403	Forbidden
プロジェクトまたは組織が見つからない	404	Not Found
上流の読み取り失敗（wf2des-api）	500	Internal Server Error

処理フロー

パスパラメータから組織 ID とプロジェクト ID を取得する。
ユーザーがプロジェクトへのアクセス権を持つことを検証する。
組織とプロジェクトにスコープした上で、内部 wf2des-api データプレーンへ読み取りをプロキシする（X-AI-Service-Token）。
文書を逐語で返す。

ファイルの登録はデータプレーン自身の登録ルートで行われ、ワーカーがファイルを初めて扱う際に使用します。本 API にユーザー向けの登録エンドポイントはありません — ファイルはオンボーディングの副作用としてこの一覧に現れます。