List WF2Des

Method

This API follows the REST methodology.

HTTP Method

GET: List wf2des Generation Runs

Returns a filterable list of wf2des generation runs (one element per wf2des row) scoped to the organization and project. The list is the discovery surface for:

• Deferred materialization — completed runs whose result frame has not yet been built (status=completed + materializedAt unset).
• Parked previews — runs waiting at the confirm checkpoint (status=processing + phase=awaiting_confirm).
• Project history — the full generation record for a project, with client-side status / date filtering.

Naming Convention

To ensure consistency and readability, JSON nodes in responses use camelCase. Query parameters use camelCase.

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

List wf2des Generation Runs

URI

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

Path Parameters

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

Query Parameters

All query parameters are optional filters combined with logical AND. Omitting every filter returns all non-deleted runs for the project. Enum filters accept the numeric-string code values stored on the row (see Status and Phase Codes).

Name	Type	Required	Description
status	string	Optional	Filter by run status code — 0 processing / 1 completed / 2 failed / 3 rejected / 4 cancelled
phase	string	Optional	Filter by generation phase code (only meaningful within status=0) — 0 parse / 1 awaiting_confirm / 2 assemble
screenId	string	Optional	Filter by screen ID
feedbackStatus	string	Optional	Filter by feedback status code — 0 fixed / 1 adopted
materialized	boolean	Optional	true returns runs with materializedAt set; false returns runs with materializedAt unset (deferred-materialization discovery)
createdFrom	string	Optional	Inclusive lower bound on createdAt (ISO 8601, e.g. 2026-07-01T00:00:00Z)
createdTo	string	Optional	Inclusive upper bound on createdAt (ISO 8601)

Request Body

None. This is a GET request; all filtering is expressed through query parameters.

Response

The response is JSON (HTTP status: 200 OK). The body is an object with a wf2desList array; each element is the same row projection returned by GET /…/wf2des/{wf2des_id}.

{
  "wf2desList": [
    {
      "wf2desId": "8f14e45f-ceea-467d-9c7b-1a2b3c4d5e6f",
      "organizationId": 1,
      "projectId": 3,
      "figmaFileKey": "aBcDeFgHiJkLmNoPqRsTuV",
      "wfNodeId": "1:42",
      "screenId": "MEM_TOP",
      "prompt": null,
      "placementTarget": null,
      "autoConfirm": "0",
      "triggerSurface": "1",
      "status": "1",
      "phase": null,
      "attempt": 1,
      "error": null,
      "resultUrl": "1/3/wf2des/runs/8f14e45f-ceea-467d-9c7b-1a2b3c4d5e6f/20260706T093000Z/result.json",
      "flagCount": 3,
      "materializedAt": null,
      "feedbackStatus": null,
      "createdAt": "2026-07-06T09:29:12Z",
      "updatedAt": "2026-07-06T09:30:44Z"
    }
  ]
}

Response Fields

Name	Type	Description
wf2desList	array	List of wf2des run projections matching the filters (empty array when none match)

wf2desList Element Fields

Each element is the projection of one wf2des PostgreSQL row.

Name	Type	Description
wf2desId	string	wf2des run ID (row id); the poll key and the worker/webhook job_id
organizationId	integer	Organization ID (tenancy scope)
projectId	integer	Project ID (tenancy scope)
figmaFileKey	string	Target Figma file key
wfNodeId	string	Target wireframe frame node ID
screenId	string | null	Screen ID, prefilled from the frame name and user-confirmed
prompt	string | null	Optional generation prompt (selection input, ranked below memo intent)
placementTarget	string | null	Optional placement node ID echoed into the result document request block
autoConfirm	string	0 normal (parse-confirm step) / 1 auto-confirm (parse + assemble in one invocation)
triggerSurface	string	0 api / 1 plugin (derived backend-side from the authenticated surface)
status	string	Run status code — 0 processing / 1 completed / 2 failed / 3 rejected / 4 cancelled
phase	string | null	Generation phase within status=0 — 0 parse / 1 awaiting_confirm / 2 assemble; null once terminal
attempt	integer	Monotonic fencing counter; always 1 today — nothing bumps it
error	string | null	Client-visible failure detail, recorded from the failed webhook manifest
resultUrl	string | null	Terminal result / failed artifact S3 key (set at completion)
flagCount	integer | null	Completion-time copy of the result document's confidence.flag_count
materializedAt	string | null	Timestamp set via the placement endpoint after the plugin builds the frame; null until materialized
feedbackStatus	string | null	0 fixed / 1 adopted (bookkeeping only)
createdAt	string	Row creation timestamp (ISO 8601)
updatedAt	string	Last update timestamp (ISO 8601)

Status and Phase Codes

The status and phase fields are stored as numeric-string enum values matching the platform convention.

status — the run lifecycle (generation only):

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 the row reaches a terminal status:

Value	Meaning
0	parse
1	awaiting_confirm
2	assemble

Data Source

All list data is read from the wf2des PostgreSQL table — the sole client-facing status surface for generation runs. The query filters on organization_id + project_id (tenancy scope) and excludes soft-deleted rows (deleted_at IS NULL). The discovery filters are served by the secondary index wf2des_org_project_file_status_idx (organization_id, project_id, figma_file_key, status).

No DocumentDB read is performed by this endpoint: flagCount and resultUrl are mirrored onto the row at completion, so consumers can discover and triage runs without a data-plane call. The native-Figma DesignSpec itself (the result artifact) is fetched separately via wf2des-api and materialized by the Figma plugin; it is not part of the list projection.

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
Project or organization not found	404	Not Found
Internal server error	500	Internal Server Error

A filter that matches no rows is not an error — the endpoint returns 200 OK with an empty wf2desList array.

Processing Flow

1. Extract organization ID and project ID from path parameters
2. Extract the optional filters (status, phase, screenId, feedbackStatus, materialized, createdFrom, createdTo) from query parameters
3. Verify the user has Read access to the project
4. Confirm the organization and project exist
5. Build the query on the wf2des table: filter by organization_id + project_id, exclude soft-deleted rows, and apply each provided filter (materialized=true → materialized_at IS NOT NULL; materialized=false → materialized_at IS NULL; date bounds against created_at)
6. Execute the query against the discovery index
7. Project each row into a camelCase element and return the wf2desList array

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| Err403[403 Forbidden]
    HasAccess -->|Yes| VerifyScope[Verify Organization / Project Exist]

    VerifyScope --> ScopeExists{Exists?}
    ScopeExists -->|No| Err404[404 Not Found]
    ScopeExists -->|Yes| BuildQuery[Build Query on wf2des table<br/>filter org_id + project_id<br/>exclude deleted_at<br/>apply status / phase / screenId /<br/>feedbackStatus / materialized / date filters]

    BuildQuery --> Execute[Execute Query<br/>discovery index]
    Execute --> Project[Project Rows to camelCase<br/>Build wf2desList array]
    Project --> Success[200 OK<br/>wf2desList array]