Get WF2Des Status

Method

This API follows the REST methodology.

HTTP Method

GET: Retrieve wf2des Status

Naming Convention

To ensure consistency and readability, JSON nodes in 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

Retrieve wf2des Status

URI

GET /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/{wf2des_id}

Path Parameters

Name	Type	Required	Description
organization_id	integer	Required	Organization ID
project_id	integer	Required	Project ID
wf2des_id	string	Required	wf2des ID

Request Body

None. This endpoint takes no request body.

Response

The response is JSON (HTTP status: 200 OK). It reflects the current state of the wf2des PostgreSQL row and is the polling target for a generation run.

{
  "wf2desId": "wf2des-001",
  "status": "0",
  "phase": "1",
  "attempt": 1,
  "error": null,
  "resultUrl": null,
  "flagCount": null,
  "materializedAt": null,
  "feedbackStatus": null,
  "screenId": "MEM_REGISTER"
}

A completed run:

{
  "wf2desId": "wf2des-001",
  "status": "1",
  "phase": null,
  "attempt": 1,
  "error": null,
  "resultUrl": "1/3/wf2des/runs/wf2des-001/20260706T093000Z/result.json",
  "flagCount": 3,
  "materializedAt": "2026-07-06T09:35:00Z",
  "feedbackStatus": null,
  "screenId": "MEM_REGISTER"
}

Response Fields

Name	Type	Description
wf2desId	string	wf2des ID (the polled row id, echoed to the worker/webhook as job_id)
status	string	Run status — 0 processing / 1 completed / 2 failed / 3 rejected / 4 cancelled (see Status Codes)
phase	string | null	Generation phase inside status 0 — 0 parse / 1 awaiting_confirm / 2 assemble. null once the row reaches a terminal status
attempt	integer	Monotonic fencing counter; always 1 today — nothing bumps it
error	string | null	Client-visible failure detail, recorded from the failed webhook manifest; null unless status is 2 failed
resultUrl	string | null	Terminal result (or failed) artifact S3 key; null until the run reaches a terminal status
flagCount	integer | null	Completion-time copy of the result document's confidence.flag_count; null until completed
materializedAt	string | null	Timestamp set once the Figma plugin has built the frame via the placement endpoint; null until materialized
feedbackStatus	string | null	0 fixed / 1 adopted, recorded by the feedback endpoint (bookkeeping only); null when no feedback recorded
screenId	string | null	Screen ID, prefilled from the frame name and user-confirmed

Status Codes

status:

Value	Meaning
0	processing
1	completed
2	failed
3	rejected (designer declined the parse; NOT failed)
4	cancelled

phase — namespaced inside status 0, independent of the status codes; null once terminal:

Value	Meaning
0	parse
1	awaiting_confirm
2	assemble

Data Source

All fields are read directly from the wf2des PostgreSQL row identified by wf2des_id. This endpoint is a status poll only — it does not return the generated design.

The generated design is a native-Figma DesignSpec stored in the design_generation_result document (DocumentDB), with its durable artifact at resultUrl (S3). The client fetches the DesignSpec through wf2des-api, and the Figma plugin materializes it into the target file. This backend endpoint never returns design content — only the row's status, phase, and result pointers.

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito.

Error Handling

The following status codes are returned for errors.

Description	Status Code	Status Name
Missing authentication credentials	401	Unauthorized
Insufficient permissions	403	Forbidden
wf2des, project, or organization not found	404	Not Found
Internal server error	500	Internal Server Error

Processing Flow

1. Extract organization ID, project ID, and wf2des_id from path parameters
2. Verify the user has Read access to the project
3. Fetch the wf2des row from PostgreSQL where id matches wf2des_id
4. If no row exists, return 404
5. Verify the row's organization_id and project_id match the path parameters
6. Format the row's status, phase, and result fields into the response and return it

Detailed Flowchart

flowchart TD
    Start([GET Request]) --> Auth[Auth & Parameter Extraction]
    Auth --> Service[Service Layer]
    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Read Access?}
    HasAccess -->|No| Err404[404 Not Found]
    HasAccess -->|Yes| QueryRow[Query PostgreSQL<br/>wf2des row<br/>WHERE id = :wf2des_id]
    QueryRow --> Exists{Row Exists?}
    Exists -->|No| Err404
    Exists -->|Yes| ScopeCheck{organization_id &<br/>project_id match?}
    ScopeCheck -->|No| Err404
    ScopeCheck -->|Yes| Format[Format Response<br/>status / phase / attempt / error /<br/>resultUrl / flagCount / materializedAt /<br/>feedbackStatus / screenId]
    Format --> Success[200 OK]