List Registered Figma Files

Method

This API follows the REST methodology.

HTTP Method

GET: List the Figma files registered for a project.

This list is what scopes a whole-file resync: the sweep walks these files and no others. It also tells the plugin which files already carry a synced component library.

Note the URI has no wf2des segment — the registration is a project-level fact, not a per-run one.

Naming Convention

The response is proxied verbatim from the internal wf2des-api data plane, so its fields are snake_case.

Request and Response

Headers

Request Headers

• Authorization
• Accept
• Accept-language

Response Headers

• Content-Type

List Figma Files

URI

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

Path Parameters

Name	Type	Required	Description
organization_id	integer	Required	Organization ID
project_id	integer	Required	Project ID

Response

The response is JSON (HTTP status: 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"
    }
  ]
}

Response Fields

Name	Type	Description
project_id	integer	The project the list belongs to.
organization_id	integer	Present only when the read was scoped to an organization.
items	object[]	One entry per registered file.

Item Fields

Name	Type	Description
figma_file_key	string	The Figma file key, verbatim. Unique per (organization_id, project_id).
role	string | null	What the file is registered as — e.g. a component library or a guideline file.
config_url	string | null	Optional configuration pointer for the file.
components_synced_at	string | null	When a component sweep last completed for this file; null when it has never been swept.

An empty items array is a normal state, not an error — it means nothing has been registered for the project yet, and a whole-file resync would have nothing to walk.

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito. The caller must additionally hold access to the project.

Error Handling

Description	Status Code	Status Name
Missing authentication credentials	401	Unauthorized
Insufficient permissions	403	Forbidden
Project or organization not found	404	Not Found
Upstream read failure (wf2des-api)	500	Internal Server Error

Processing Flow

1. Extract organization ID and project ID from path parameters.
2. Verify the user has access to the project.
3. Proxy the read to the internal wf2des-api data plane (X-AI-Service-Token), scoped to the organization and project.
4. Return the document verbatim.

Files are registered on the data plane's own registration route, which the worker uses when it first encounters a file. There is no user-facing registration endpoint on this API — a file appears in this list as a side effect of onboarding it.