Skip to content

Resync Component Registry

Method

This API follows the REST methodology.

HTTP Method

POST: Trigger a whole-file component registry resync โ€” enqueue a resync event, which routes to an unscoped component_sweep.

Where POST โ€ฆ/wf2des/components is additive and sweeps only the boards a designer selected, resync re-walks every Figma file registered for the project. Use it when the library has changed broadly and the registry should be reconciled against it.

The request takes no body โ€” the scope is "everything registered for this project", which the worker reads from the project's Figma-file list (see GET โ€ฆ/figma-files).

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

Request Headers

  • Authorization
  • Accept
  • Accept-language

Response Headers

  • Content-Type

Resync Registry

URI

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

Path Parameters

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

Request Body

None. This endpoint takes no request body.

Response

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

{
  "organizationId": 1,
  "projectId": 7,
  "event": "resync",
  "eventRunId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e73"
}

Response Fields

Name Type Description
organizationId integer Echoed from the path.
projectId integer Echoed from the path.
event string Always the literal resync.
eventRunId string Poll GET โ€ฆ/wf2des/events/{eventRunId}/status for live progress.

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

Note there is no 400 โ€” the endpoint has no request body to reject.

Description Status Code Status Name
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.
  2. Verify the user has Write access to the project.
  3. Mint a fresh eventRunId.
  4. Send the resync event to the wf2des-events SQS queue.
  5. Return 202 with the poll handle.

Asynchronous Processing

The resync event routes to a whole-file component_sweep. The worker reads the project's registered Figma files to scope its walk, then sweeps each file for COMPONENT / COMPONENT_SET definitions and remote-library instances, upserting every one into design_component.

The same scheduled sweep runs on an AI-owned EventBridge schedule; this endpoint is the on-demand trigger for the identical run.

A resync cannot downgrade a record that carries provenance: "plugin-observed" โ€” captures submitted through POST โ€ฆ/wf2des/component-captures survive it. That property is what makes running a resync safe after a capture pass.

component_sweep is an internal run โ€” no ai-status webhook, no PostgreSQL effect beyond the backend's own component-registry upserts.

SQS Payload

{
  "event_type": "resync",
  "organization_id": 1,
  "project_id": 7,
  "event_run_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e73"
}

SQS Payload Fields

Name Type Required Description
event_type string Required Always resync; 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.

The payload carries no file key or node ids โ€” the sweep's scope is the project's registered Figma-file list, which the worker reads for itself.