Full implementation of Figma API.
Figma api's file fully typed with TypeScript.
Both browser & nodejs supported.
Promises & ES6.
npm i figma-api
or browser version:
https://raw.githubusercontent.com/Morglod/figma-api/master/lib/figma-api.js
https://raw.githubusercontent.com/Morglod/figma-api/master/lib/figma-api.min.js
All api in browser exported to global Figma
object.
import * as Figma from 'figma-api';
export async function main() {
const api = new Figma.Api({
personalAccessToken: 'my token',
});
const file = await api.getFile('my file key');
// ... access file data ...
}
or in browser:
const api = new Figma.Api({ personalAccessToken: 'my token' });
api.getFile('my file key').then((file) => {
// access file data
});
Change API endpoint setting Figma.API_DOMAIN
& Figma.API_VER
variables.
We have followed the same organisation as the official Figma API documentation to describe our API methods, so it's easier to find the exact endpoint call you are looking for.
Creates new Api object with specified personal
or oAuthToken
.
Documentation on how to get tokens
Api.getFile
Api.getFile(fileKey, opts?: { version?, geometry? })
Require file data with specified version.
Set geometry='paths'
to export vector data.
Returns:
{
name: string,
lastModified: string,
thumbnailURL: string,
version: string,
document: Node<'DOCUMENT'>,
components: { [nodeId: string]: Component },
schemaVersion: 0,
styles: { [styleName: string]: Style }
}
Api.getFileNodes
Api.getFileNodes(fileKey, ids, opts?: { version?, geometry? })
Require file nodes data with specified version.
Set geometry='paths'
to export vector data.
Returns:
{
name: string,
lastModified: string,
thumbnailURL: string,
err: string,
nodes: {
id: {
document: Node<'DOCUMENT'>,
components: { [nodeId: string]: Component },
schemaVersion: 0,
styles: { [styleName: string]: Style }
}
}
}
Api.getImage
Api.getImage(fileKey, opts?: {
/** A comma separated list of node IDs to render */
ids: string,
/** A number between 0.01 and 4, the image scaling factor */
scale: number,
/** Image output format */
format: 'jpg'|'png'|'svg',
/** Whether to include id attributes for all SVG elements. `Default: false` */
svg_include_id?: boolean,
/** Whether to simplify inside/outside strokes and use stroke attribute if possible instead of <mask>. `Default: true` */
svg_simplify_stroke?: boolean,
/** A specific version ID to get. Omitting this will get the current version of the file */
version?: string,
})
Renders images from a file.
Returns:
{
err: string,
images: { [nodeId: string]: string|null },
status: number
}
Api.getImageFills
Api.getImageFills(fileKey)
Returns download links for all images present in image fills in a document.
Returns:
{
images?: {
[imageRef: string]: imageUrl,
},
}
Api.getComments
Api.getComments(fileKey)
List of comments left on the file.
Returns:
{
comments: Comment[],
}
Api.postComment
Api.postComment(fileKey, message, client_meta, comment_id?)
Posts a new comment on the file.
Returns:
Comment
Api.deleteComments
Api.deleteComment(fileKey, comment_id)
Deletes a specific comment. Only the person who made the comment is allowed to delete it.
Returns:
Nothing is returned from this endpoint
Api.getMe
Api.getMe()
You can use the Users Endpoint to access information regarding the currently authenticated User. When using OAuth 2, the User in question must be authenticated through the Figma API to access their information.
Returns:
User
Api.getVersions
Api.getVersions(fileKey)
A list of the version history of a file. The version history consists of versions, manually-saved additions to the version history of a file. If the account is not on a paid team, version history is limited to the past 30 days. Note that version history will not include autosaved versions.
Returns:
{
versions: Version[]
}
Api.getTeamProjects
Api.getTeamProjects(team_id)
Lists the projects for a specified team. Note that this will only return projects visible to the authenticated user or owner of the developer token. Note: it is not currently possible to programmatically obtain the team id of a user just from a token. To obtain a team id, navigate to a team page of a team you are a part of. The team id will be present in the URL after the word team and before your team name.
Returns:
{
name: string,
projects: { id: number, name: string }[],
}
Api.getProjectFiles
Api.getProjectFiles(project_id)
List the files in a given project.
Returns:
{
files: {
key: string,
name: string,
thumbnail_url: string,
last_modified: string,
}[],
}
Api.getTeamComponents
Api.getTeamComponents(team_id, opts?: { page_size?, cursor? })
Get a paginated list of published components within a team library.
Returns:
{
error: boolean,
meta: {
components: [
/* ComponentMetadata */ {
key: string,
file_key: string,
node_id: string,
thumbnail_url: string,
name: string,
description: string,
updated_at: string,
created_at: string,
user: User,
containing_frame: FrameInfo,
},
],
cursor: {
before: number,
after: number,
},
},
status: number
}
Api.getFileComponents
Api.getFileComponents(fileKey)
Get a list of published components within a file library.
Returns:
{
error: boolean,
meta: {
components: [
/* ComponentMetadata */ {
key: string,
file_key: string,
node_id: string,
thumbnail_url: string,
name: string,
description: string,
updated_at: string,
created_at: string,
user: User,
containing_frame: FrameInfo,
},
],
},
status: number
}
Api.getComponent
Api.getComponent(componentKey)
Get metadata on a component by key.
Returns:
{
error: boolean,
meta: {
/* ComponentMetadata */ {
key: string,
file_key: string,
node_id: string,
thumbnail_url: string,
name: string,
description: string,
updated_at: string,
created_at: string,
user: User,
containing_frame: FrameInfo,
},
},
status: number
}
Api.getTeamComponentSets
Api.getTeamComponentSets(team_id, opts?: { page_size?, after?, before? })
Get a paginated list of published component_sets within a team library.
Returns:
{
error: boolean,
meta: {
component_sets: [
/* ComponentSetMetadata */ {
key: string,
file_key: string,
node_id: string,
thumbnail_url: string,
name: string,
description: string,
updated_at: string,
created_at: string,
user: User,
containing_frame: FrameInfo,
},
],
cursor: {
before: number,
after: number,
},
},
status: number
}
Api.getFileComponentSets
Api.getFileComponentSets(file_key)
Get a list of published component_sets within a file library.
Returns:
{
error: boolean,
meta: {
component_sets: [
/* ComponentSetMetadata */ {
key: string,
file_key: string,
node_id: string,
thumbnail_url: string,
name: string,
description: string,
updated_at: string,
created_at: string,
user: User,
containing_frame: FrameInfo,
},
],
},
status: number
}
Api.getComponentSet
Api.getComponentSet(componentsetKey)
Get metadata on a component_set by key.
Returns:
{
error: boolean,
meta: {
/* ComponentSetMetadata */ {
key: string,
file_key: string,
node_id: string,
thumbnail_url: string,
name: string,
description: string,
updated_at: string,
created_at: string,
user: User,
containing_frame: FrameInfo,
}
},
status: number
}
Api.getTeamStyles
Api.getTeamStyles(team_id, opts?: { page_size?, cursor? })
Get a paginated list of published styles within a team library.
Returns:
{
error: boolean,
meta: {
styles: [
{
key: string,
file_key: string,
node_id: string,
style_type: StyleType,
thumbnail_url: string,
name: string,
description: string,
updated_at: string,
created_at: string,
sort_position: string,
user: User,
},
],
cursor: {
before: number,
after: number,
},
},
status: number
}
Api.getFileStyles
Api.getFileStyles(file_key)
Get a list of published styles within a file library.
Returns:
{
error: boolean,
meta: {
styles: [
{
key: string,
file_key: string,
node_id: string,
style_type: StyleType,
thumbnail_url: string,
name: string,
description: string,
updated_at: string,
created_at: string,
sort_position: string,
user: User,
},
],
},
status: number
}
Api.getStyle
Api.getStyle(styleKey)
Get metadata on a style by key.
Returns:
error: boolean,
meta: {
{
key: string,
file_key: string,
node_id: string,
style_type: StyleType,
thumbnail_url: string,
name: string,
description: string,
updated_at: string,
created_at: string,
sort_position: string,
user: User,
},
},
status: number
}
Helpers
Api.appendHeaders(headers: {}): void
Populate headers with auth.
Api.request<T>(url, opts): Promise<T>
Make request with auth headers.
function oAuthLink(
client_id: string,
redirect_uri: string,
scope: 'file_read',
state: string,
response_type: 'code',
): string;
Returns link for OAuth auth flow.
User should open this link, allow access and he will be redirected to redirect_uri?code=<code>
.
Then you should use oAuthToken
method to get access token
.
function oAuthToken(
client_id: string,
client_secret: string,
redirect_uri: string,
code: string,
grant_type: 'authorization_code',
): Promise<{
access_token: string,
refresh_token: string,
expires_in: number,
}>
Returns access token
info from oauth code (see oAuthLink
method).
Helpers
isEffectShadow(effect: Effect): effect is EffectShadow;
Check if effect is one of shadow effects.
isEffectBlur(effect: Effect): effect is EffectBlur;
Check if effect is one of blur effects.
isPaintSolid(paint: Paint): paint is PaintSolid;
isPaintGradient(paint: Paint): paint is PaintGradient;
isPaintImage(paint: Paint): paint is PaintImage;
Check if paint is one of pain types.
isNodeType<NodeType>(node: Node): node is type of NodeType;
Check if node is type of specified node.
git clone https://github.com/Morglod/figma-api.git
cd figma-api
git checkout dev
npm i
npm run build