Skip to content

Register Wireframe Frame

Method

This API follows the REST methodology.

HTTP Method

POST: Register a wireframe frame โ€” capture its snapshot server-side and enqueue a frame_registration event, which routes to the worker's wf_parse run and caches the parsed wireframe tree.

Registration is a warm-up, not a generation. It produces no wf2des PostgreSQL row and no design; it parses the frame ahead of time so a later trigger can reuse the cached tree.

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

Register Frame

URI

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

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",
  "nodeId": "2:264664"
}

Request Parameters

Name Type Required Description
figmaFileKey string Required The Figma file the frame lives in. Figma verbatim โ€” alphanumeric, no underscore (^[A-Za-z0-9]+$).
nodeId string Required The wireframe frame node id to register (^[A-Za-z0-9:;_-]+$).

Response

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

{
  "figmaFileKey": "abc123XYZ",
  "nodeId": "2:264664",
  "snapshotUrl": "s3://dev-guinness-backend/1/7/wf2des/2_264664/wireframe.json",
  "wfContentHash": "8f14e45fceea167a5a36dedd4bea2543"
}

Response Fields

Name Type Description
figmaFileKey string Echoed from the request.
nodeId string Echoed from the request.
snapshotUrl string The backend-captured wireframe snapshot (s3://) enqueued for wf_parse.
wfContentHash string Content hash of the captured wireframe. Identifies the parsed tree in the cache.

202, not 200 โ€” the response confirms the event was enqueued, not that parsing finished. This endpoint returns no eventRunId; wf_parse is an internal run with no live-status document, so there is nothing to poll. Its effect is observed indirectly: a later generation trigger on the same frame reuses the cached parse.

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 / nodeId absent or failing their pattern) 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
Snapshot capture failed, or the SQS send failed 500 Internal Server Error

Processing Flow

  1. Extract organization ID and project ID from path parameters; extract figmaFileKey and nodeId from the request body.
  2. Verify the user has Write access to the project.
  3. Capture the wireframe snapshot server-side โ€” resolve the node, walk its subtree, and write the wireframe JSON to S3. The snapshot is scoped to the board, never the whole canvas.
  4. Send the frame_registration event to the wf2des-events SQS queue.
  5. Return 202 with the snapshot pointer and content hash.

Asynchronous Processing

The frame_registration event routes to the worker's wf_parse run, which reads the snapshot, parses the wireframe into roles and intent, and writes the result to the wireframe DocumentDB collection keyed by content hash.

wf_parse is an internal run: it emits no ai-status webhook and has no PostgreSQL effect. Failure is visible only through output-document freshness and the SQS dead-letter queue.

SQS Payload

{
  "event_type": "frame_registration",
  "organization_id": 1,
  "project_id": 7,
  "figma_file_key": "abc123XYZ",
  "node_id": "2:264664",
  "snapshot_url": "s3://dev-guinness-backend/1/7/wf2des/2_264664/wireframe.json"
}

SQS Payload Fields

Name Type Required Description
event_type string Required Always frame_registration; the queue's discriminator.
organization_id integer Required Organization ID.
project_id integer Required Project ID.
figma_file_key string Required The Figma file, verbatim.
node_id string Required The registered wireframe frame node id.
snapshot_url string Required The captured wireframe snapshot the worker reads.