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.

info

API versions apply per endpoint. The /v2 folder endpoints replace deprecated project endpoints; the /v1 endpoints are separate operations.

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

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

POST team folder

Creates a top-level folder in a team. The team must belong to the Enterprise plan associated with the private OAuth app, and the authenticated user must be allowed to create a folder in the team.

info

This is a Tier 2 endpoint, requires the folders:write scope, and is available only to private OAuth apps associated with an Enterprise plan.

HTTP Endpoint

POST /v1/teams/:team_id/folders

Path parameters	Description
team_id	String The ID of the team in which to create the folder.

Body parameters	Description
name	String The name of the folder.
sharing_audience_control	String The audience that can access the folder: plan_view, plan_edit, invite_only, workspace_view, or workspace_edit. Workspace audiences require the specified team to belong to a workspace.

Return value

Returns the created Folder, including sharing_audience_control and created_at.

Error codes	Description
400	The request parameters are invalid.
401	The access token is missing or incorrect.
403	The caller does not have permission to create the folder.
404	The requested resource was not found.
429	The request was rate-limited.
500	An internal server error occurred.