Figma API

Give the agent your designs, with a scoped Figma access token.

Connect a Figma account to your project and the build agent can read your frames, layout, spacing, colours, text and variables — and build real components from them instead of guessing. All endpoints require the api-key header and are free.

Why a token and not "Sign in with Figma"

Figma's official remote MCP server requires an interactive OAuth browser sign-in and does not support personal access tokens. Totalum's agent runs on a headless sandbox with no browser, so it authenticates with a scoped token you create yourself. That token stays encrypted and is only ever used by your own project's agent.

#Connect Figma

POST/api/v1/vcaas/projects/:projectId/figma/connectFree

Link a Figma account to your project. The token is validated against Figma's own API before anything is stored, so an invalid token changes nothing and you get back the specific reason rather than a generic failure.

Create a Figma token

In Figma, open Settings and go to the Security tab.
Under Personal access tokens, click "Generate new token".
Set an expiration you're comfortable with.
Select the scopes current_user:read and file_content:read.
Click "Generate token" and copy it (it starts with figd_).

Organization and Enterprise plans

You can use a plan access token instead of a personal one. It is user-agnostic — it keeps working when someone leaves the team — and authenticates exactly the same way, so it's usually the better choice for a team.

Path parameters

Parameter	Type	Description
`projectId`	string	The project ID

Body parameters

Field	Type	Required	Description
`token`	string	Yes	Figma personal access token, or an Organization/Enterprise plan access token

Response fields

Field	Type	Description
`data.connected`	boolean	true if the connection succeeded
`data.account.id`	string	Figma user ID
`data.account.handle`	string	Figma display name
`data.account.email`	string	Email on the Figma account
`data.account.imgUrl`	string	Avatar URL

Errors

Error Code	HTTP	Description
`MISSING_FIGMA_TOKEN`	400	`token` is required
`FIGMA_TOKEN_MALFORMED`	400	That doesn't look like a Figma token — whitespace, a URL, or far too short
`FIGMA_TOKEN_INVALID`	400	Figma rejected the token: wrong, expired or revoked
`FIGMA_TOKEN_FORBIDDEN`	400	The token is valid but is missing the scopes Totalum needs
`FIGMA_RATE_LIMITED`	400	Figma is rate-limiting the request — retry shortly
`FIGMA_UNREACHABLE`	400	Figma couldn't be reached to validate the token

The token is never returned

No endpoint returns your Figma token. It is stored encrypted, is never written to a log, and connected projects report the account — not the credential.

bash

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"token":"figd_xxx"}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/figma/connect

json

{
  "errors": null,
  "data": {
    "connected": true,
    "account": {
      "id": "123456",
      "handle": "Ada Lovelace",
      "email": "ada@example.com",
      "imgUrl": "https://s3-alpha.figma.com/..."
    }
  }
}

End of Connect FigmaNext endpointGETGet Figma Status

#Get Figma Status

GET/api/v1/vcaas/projects/:projectId/figma/statusFree

Check whether Figma is connected and which account is linked.

Query parameters

Field	Type	Required	Description
`verify`	boolean	No	`true` re-checks the stored token against Figma. This costs a live Figma call — use it when a screen opens, not on a poll

Response fields

Field	Type	Description
`data.connected`	boolean	Whether Figma is connected
`data.account`	object	The linked account (`id`, `handle`, `email`, `imgUrl`)
`data.connectedAt`	string	When the connection was made
`data.tokenValid`	boolean	Only with `verify=true` — whether Figma still accepts the token
`data.tokenError`	string	Only with `verify=true` and a failure — the specific reason

A failed re-check never disconnects you

tokenValid: false means "this token stopped working, paste a new one". The connection is left in place — a Figma outage never silently removes your integration.

bash

curl -H "api-key: tlm_sk_your_key" \
  "https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/figma/status?verify=true"

json

{
  "errors": null,
  "data": {
    "connected": true,
    "account": { "id": "123456", "handle": "Ada Lovelace" },
    "connectedAt": "2026-08-03T10:24:00.000Z",
    "tokenValid": true
  }
}

End of Get Figma StatusNext endpointDELETEDisconnect Figma

#Disconnect Figma

DELETE/api/v1/vcaas/projects/:projectId/figma/connectFree

Remove the Figma integration from your project. The stored token is deleted and the agent stops being able to read your designs. Nothing in your Figma account changes.

This endpoint is idempotent — a project that was never connected also returns 200.

Response fields

Field	Type	Description
`data.disconnected`	boolean	true on success
`data.message`	string	Confirmation message

bash

curl -X DELETE -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/figma/connect

json

{
  "errors": null,
  "data": { "disconnected": true, "message": "Figma disconnected successfully" }
}

End of Disconnect FigmaNext sectionUsing it in a prompt

#Using it in a prompt

Once connected, paste a Figma link into a prompt and the agent reads that frame:

Build the pricing section from this design:
https://www.figma.com/design/AbC123/My-Product?node-id=42-1337

In Figma, right-click a frame and choose Copy link to selection to get a URL that points at exactly the frame you mean.

End of Using it in a prompt Back to top