Skip to content

Upload Rule Boards

Method

This API follows the REST methodology.

HTTP Method

POST: Upload guideline boards โ€” enqueue a rule_upload event, which routes to the worker's rule_process run and lands one immutable rule revision.

Every upload produces a new revision; earlier revisions are never modified or deleted. A fresh upload also clears any active revert pin, because uploading is a deliberate "this is now current".

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 Rule Boards

URI

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

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": ["2:100", "2:101", "2:102"],
  "designRuleId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e6f"
}

Request Parameters

Name Type Required Description
figmaFileKey string Required The guideline file the boards live in. Figma verbatim (^[A-Za-z0-9]+$).
boardNodeIds string[] Required Selected guideline board frames โ€” at least one. A CANVAS or SECTION container is accepted and expanded to its child board frames by the worker.
designRuleId string Optional An existing design_rule id to add a revision to. A fresh UUID is minted when omitted, starting a new rule lineage at version 1.

Response

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

{
  "eventRunId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e70",
  "designRuleId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e6f",
  "figmaFileKey": "abc123XYZ",
  "boardNodeIds": ["2:100", "2:101", "2:102"]
}

Response Fields

Name Type Description
eventRunId string Poll GET โ€ฆ/wf2des/events/{eventRunId}/status for live progress. This run is long โ€” see below.
designRuleId string The rule lineage the new revision belongs to (echoed, or the freshly minted id).
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 designRuleId when the request omitted it, and mint a fresh eventRunId.
  4. Send the rule_upload event to the wf2des-events SQS queue.
  5. Return 202 with the poll handle.

Asynchronous Processing

The rule_upload event routes to rule_process. Per board the worker renders the board image, reads its node text, comprehends the board, routes it to the extractors its content warrants, and extracts verbatim. It then merges every board deterministically โ€” authority-gated, no LLM judge โ€” and lands one immutable revision holding both the merged ruleset and its source boards.

This is the longest run in the system. Boards are processed concurrently, but a large guideline still takes minutes; the plugin's progress stepper is driven by the eventRunId poll. Fabrication is structurally impossible: every extracted string is a verbatim substring of the board's own node text.

rule_process is an internal run โ€” no ai-status webhook, no PostgreSQL effect. Its output is the new revision in the design_rule collection, observable through GET โ€ฆ/wf2des/rules/latest.

SQS Payload

{
  "event_type": "rule_upload",
  "organization_id": 1,
  "project_id": 7,
  "event_run_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e70",
  "design_rule_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e6f",
  "figma_file_key": "abc123XYZ",
  "board_node_ids": ["2:100", "2:101", "2:102"]
}

SQS Payload Fields

Name Type Required Description
event_type string Required Always rule_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.
design_rule_id string Required The rule lineage the new revision joins.
figma_file_key string Required The guideline file, verbatim.
board_node_ids string[] Required The selected boards; containers are expanded worker-side.