Skip to content

Upload Component Boards

Method

This API follows the REST methodology.

HTTP Method

POST: Upload component-library boards โ€” enqueue a component_upload event, which routes to a scoped component_sweep. The worker walks only the selected boards' subtrees for COMPONENT / COMPONENT_SET definitions and remote-library instances, and upserts each into the component registry.

Additive. Unlike resync, which re-sweeps the whole file, this never touches components outside the selected boards.

Naming Convention

To ensure consistency and readability, JSON nodes in requests and responses use camelCase. SQS payload nodes use snake_case.

Request and Response

Headers

Meta information is set in HTTP headers, not in the response body.

Request Headers

  • Authorization
  • Content-Type
  • Accept
  • Accept-language

Response Headers

  • Content-Type

Upload Component Boards

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/components

Path Parameters

Name Type Required Description
organization_id integer Required Organization ID
project_id integer Required Project ID

Request Body

The request body is JSON.

{
  "figmaFileKey": "abc123XYZ",
  "boardNodeIds": ["10:200", "10:201"],
  "styleCaptures": {
    "color/primary": "VariableID:1:23",
    "spacing/md": "VariableID:1:45"
  }
}

Request Parameters

Name Type Required Description
figmaFileKey string Required The component-library file the boards live in. Figma verbatim (^[A-Za-z0-9]+$).
boardNodeIds string[] Required Selected component-library board frames โ€” at least one. A CANVAS or SECTION container is accepted and expanded worker-side.
styleCaptures object (stringโ†’string) Optional Plugin-captured token โ†’ VariableID:โ€ฆ map โ€” the file's local Figma Variables, read via figma.variables.*. Merged into style_captures so generation can bind live variables.

Response

The response is JSON (HTTP status: 202 Accepted).

{
  "eventRunId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e71",
  "figmaFileKey": "abc123XYZ",
  "boardNodeIds": ["10:200", "10:201"]
}

Response Fields

Name Type Description
eventRunId string Poll GET โ€ฆ/wf2des/events/{eventRunId}/status for live progress.
figmaFileKey string Echoed from the request.
boardNodeIds string[] Echoed from the request โ€” the selection, before the worker expands containers.

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito. The caller must additionally hold Write access to the project.

Error Handling

The following status codes are returned for errors.

Description Status Code Status Name
Invalid body (figmaFileKey malformed, boardNodeIds empty or malformed) 400 Bad Request
Missing authentication credentials 401 Unauthorized
Insufficient permissions (no Write access to the project) 403 Forbidden
Project or organization not found 404 Not Found
SQS send failure 500 Internal Server Error

Processing Flow

  1. Extract organization ID and project ID from path parameters; extract the body.
  2. Verify the user has Write access to the project.
  3. Mint a fresh eventRunId.
  4. Send the component_upload event to the wf2des-events SQS queue. The backend forwards the selected node ids only โ€” the worker resolves and walks the boards itself.
  5. Return 202 with the poll handle.

Asynchronous Processing

The component_upload event routes to a scoped component_sweep. Per component the worker records the publish key, variant axes, text slots and default size, then upserts it into the design_component registry.

The sweep reads through the Figma REST API, which cannot see inside a design-system library: a remote component is only observable through an instance of it, so the sweep can land keyless local twins with fragmentary variant axes. POST โ€ฆ/wf2des/component-captures exists to correct exactly that, and the plugin normally sends captures as a second pass after this upload completes.

component_sweep is an internal run โ€” no ai-status webhook. Its registry effect is observable through GET โ€ฆ/wf2des/registry.

SQS Payload

{
  "event_type": "component_upload",
  "organization_id": 1,
  "project_id": 7,
  "event_run_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e71",
  "figma_file_key": "abc123XYZ",
  "board_node_ids": ["10:200", "10:201"],
  "style_captures": { "color/primary": "VariableID:1:23" }
}

SQS Payload Fields

Name Type Required Description
event_type string Required Always component_upload; the queue's discriminator.
organization_id integer Required Organization ID.
project_id integer Required Project ID.
event_run_id string Required Correlates the live-status document the plugin polls.
figma_file_key string Required The component-library file, verbatim.
board_node_ids string[] Required The selected boards; containers are expanded worker-side.
style_captures object Required Token โ†’ VariableID:โ€ฆ map. Defaults to {} when the request omits it.