Endpoints

See information about your folders, subfolders, and files within a folder.

info

Limited Access

The endpoints that require the folders:read scope cannot be used with public OAuth apps. GET folder metadata, which requires folder_metadata:read, is available to all OAuth apps.

GET team folders

Get a list of the top-level folders within the specified team. It returns only folders visible to the authenticated user or owner of the token, accounting for direct roles, inherited access, sharing audience controls, and user groups. Each returned folder has a null parent_folder_id. Use GET folder subfolders to traverse into subfolders.

It is not possible to programmatically obtain team IDs. To obtain a team ID, navigate to the team page in the Figma file browser. The team ID is present in the URL after the word team. For example, in https://www.figma.com/files/181033233908053158/team/1535685101263221741, the team ID is 1535685101263221741.

info

This is a Tier 2 endpoint and requires the folders:read scope.

HTTP Endpoint

GET /v2/teams/:team_id/folders

Path parameters	Description
team_id	String ID of the team to list folders from

Error codes	Description
400	Error with the request. The "message" param on the response will describe the error.
403	The developer / OAuth token is invalid or expired, or does not have access to the team
404	The specified team was not found

GET folder subfolders

List the direct subfolders within a given folder (folders whose parent_folder_id equals the requested folder's ID). It returns only folders visible to the authenticated user or owner of the token.

info

This is a Tier 2 endpoint and requires the folders:read scope.

HTTP Endpoint

GET /v2/folders/:folder_id/folders

Path parameters	Description
folder_id	String ID of the parent folder to list subfolders from

Error codes	Description
400	Error with the request. The "message" param on the response will describe the error.
403	The developer / OAuth token is invalid or expired, or does not have access to the folder
404	The specified folder was not found

GET folder files

List the files directly within a given folder. It returns only files visible to the authenticated user or owner of the token.

info

This is a Tier 2 endpoint and requires the folders:read scope.

HTTP Endpoint

GET /v2/folders/:folder_id/files

Path parameters	Description
folder_id	String ID of the folder to list files from

Query parameters	Description
branch_data	Booleandefault: false Returns branch metadata in the response for each main file with a branch inside the folder.

Error codes	Description
400	Error with the request. The message param on the response will describe the error.
403	The developer / OAuth token is invalid or expired, or does not have access to the folder
404	The specified folder was not found

GET folder metadata

Returns basic metadata about a folder — its name, thumbnail, file count, and timestamps — without enumerating its files. Use this when you need a lightweight folder preview, such as for link unfurling or search results. This is the v2 replacement for the project metadata endpoint. thumbnail_url may be null if the folder has no files.

info

This is a Tier 3 endpoint and requires the folder_metadata:read scope.

HTTP Endpoint

GET /v2/folders/:folder_id/meta

Return value

{
  "id": String,
  "name": String,
  "thumbnail_url": String,
  "file_count": Number,
  "updated_at": String,
  "created_at": String
}

Path parameters	Description
folder_id	String ID of the folder to get metadata for

Error codes	Description
403	The developer / OAuth token is invalid or expired, or does not have access to the folder
404	The specified folder was not found
429	The request was rate-limited