Figma REST API Client

2.1.2-beta · active · verified Tue Apr 21

The `figma-api` package provides a thin, typed JavaScript/TypeScript wrapper around the official Figma REST API. Currently in its 2.1.2-beta version, this library offers a client-side implementation designed for both browser and Node.js environments. It leverages Promises via Axios for HTTP requests and is fully typed with TypeScript, aligning its API methods directly with the official Figma REST API specifications. A significant rewrite occurred in version 2.x, standardizing endpoint method names and argument structures to precisely match Figma's documentation, ensuring future consistency. The package differentiates itself by closely mirroring the official API spec, providing a robust, type-safe interface for interacting with Figma files and resources programmatically, making it easier for developers to build integrations without constantly referring to external documentation for method signatures.

Common errors

```
TypeError: Figma.Api is not a constructor
```
cause Attempting to import `Api` as a named import (e.g., `import { Api }`) instead of using a namespace import, or incorrectly accessing it after a CommonJS `require`.

fix Use a namespace import: `import * as Figma from 'figma-api';` and then access the class as `new Figma.Api(...)`. If using CommonJS, which is not officially supported for modern versions, module interop might be needed or consider transpiling.
```
Property 'getFile' does not exist on type 'Api' or 'TypeError: api.getFile is not a function'
```
cause Attempting to call an API method with the old v1.x signature (e.g., `api.getFile('file-key')`) or on an outdated instance after upgrading to v2.x.

fix Ensure your code uses the v2.x API method names and argument structures, which expect parameters to be passed within objects (e.g., `api.getFile({ file_key: '...' })`). Consult the official Figma REST API documentation for correct endpoint signatures.
```
Error: Request failed with status code 403
```
cause The provided `personalAccessToken` or `oAuthToken` is invalid, expired, or lacks the necessary permissions for the requested operation.

fix Verify that your Figma token is correct, not expired, and has the required 'file_read' or other necessary scopes for the API call you are making. Generate a new token from Figma settings if unsure.
```
Error: Network Error (or) Cross-Origin Request Blocked by CORS policy
```
cause Client-side browser environment is blocking the request due to CORS policies, or there's a general network connectivity issue preventing the request from reaching Figma's API.

fix If in a browser, ensure your application's origin is allowed by Figma (which it generally is for standard API calls) or that your browser environment isn't imposing stricter local policies. For Node.js, check network connectivity. If using a direct CDN link in the browser, consider bundling with npm to mitigate CORS, or implement a proxy.

Warnings

breaking Version 2.x is a complete rewrite with significant breaking changes from 1.x. All endpoint methods have been renamed, and their arguments now consistently use objects (e.g., `pathParams`, `queryParams`, `requestBody`) instead of direct individual values.
Fix: Refer to the official Figma REST API documentation for updated method names and argument structures. Update all API calls to match the new object-based parameter passing (e.g., `api.getFile({ file_key: '...' })`).
gotcha The library is currently distributed as a beta version (e.g., 2.1.2-beta). While actively maintained, users should be aware of its pre-stable status and potential for further minor adjustments before a stable 2.0.0 release.
Fix: Monitor the project's GitHub releases and NPM for stable version announcements. For production applications, consider locking to a specific beta version or preparing for minor updates.
gotcha When using the browser version directly via CDN links (e.g., `figma-api.min.js`), you might encounter Cross-Origin Resource Sharing (CORS) limitations if the API requests are not made from a whitelisted origin.
Fix: For browser usage, it is recommended to install the library via npm (`npm i figma-api`) and bundle it with your application. Alternatively, ensure your server-side proxy handles CORS headers correctly, or configure your Figma API client with a proxy if available.
gotcha Authentication requires either a `personalAccessToken` or an `oAuthToken`. Misconfiguring or providing an invalid token will result in API errors (e.g., HTTP 403 Forbidden).
Fix: Ensure you are using a valid personal access token obtained from Figma, or correctly implementing the OAuth 2.0 flow to acquire and refresh access tokens. Verify that the token has the necessary permissions (scopes) for the desired API operations.

Install

npm install figma-api npm
yarn add figma-api yarn
pnpm add figma-api pnpm

Imports

Api

wrong:

import { Api } from 'figma-api';
const api = new Api({ personalAccessToken: process.env.FIGMA_TOKEN });

correct:

import * as Figma from 'figma-api';
const api = new Figma.Api({ personalAccessToken: process.env.FIGMA_TOKEN });

Since version 2.x, the `Api` class is exposed as part of a namespace import (`* as Figma`). Direct named imports like `import { Api } ...` will result in a `TypeError`.

oAuthLink
wrong:
```
const Figma = require('figma-api');
const oauthUrl = Figma.oAuthLink(...);
```
correct:
```
import * as Figma from 'figma-api';
const oauthUrl = Figma.oAuthLink('CLIENT_ID', 'REDIRECT_URI', 'file_read', 'STATE_STRING', 'code');
```
Helper functions like `oAuthLink` are exposed via the `Figma` namespace. The library is primarily designed for ESM environments, and CommonJS `require` patterns may not provide the expected exports in v2.x.

oAuthToken

wrong:

import { oAuthToken } from 'figma-api';
const tokenResponse = await oAuthToken(...);

correct:

import * as Figma from 'figma-api';
const tokenResponse = await Figma.oAuthToken('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URI', 'CODE', 'authorization_code');

Similar to `oAuthLink`, the `oAuthToken` function is accessed via the `Figma` namespace from a wildcard import. Named imports for these specific helper functions are incorrect and will not work.

Quickstart

Demonstrates how to initialize the Figma API client with a personal access token, fetch a specific Figma file by its key, and then log some basic information about the retrieved file structure, handling potential errors.

import * as Figma from 'figma-api';

const personalAccessToken = process.env.FIGMA_PERSONAL_ACCESS_TOKEN ?? '';
const fileKey = process.env.FIGMA_FILE_KEY ?? '';

if (!personalAccessToken || !fileKey) {
  console.error('Please set FIGMA_PERSONAL_ACCESS_TOKEN and FIGMA_FILE_KEY environment variables.');
  process.exit(1);
}

export async function getFigmaFile() {
    try {
        console.log('Initializing Figma API client...');
        const api = new Figma.Api({
            personalAccessToken: personalAccessToken,
        });

        console.log(`Fetching file with key: ${fileKey}...`);
        // The getFile method in v2.x expects an object with parameters
        const file = await api.getFile({ file_key: fileKey });

        console.log('Successfully fetched Figma file structure.');
        // Accessing basic file data
        console.log(`File Name: ${file.name}`);
        console.log(`Last modified: ${file.lastModified}`);
        console.log(`Number of top-level children: ${file.document?.children?.length ?? 0}`);
        
        return file;
    } catch (error) {
        console.error('Error fetching Figma file:', error.message);
        if (error.response) {
          console.error('Response data:', error.response.data);
          console.error('Response status:', error.response.status);
        }
        throw error;
    }
}

// Execute the function when the script runs
getFigmaFile().catch(err => {
  console.error('Figma API operation failed:', err);
});

view raw JSON →