Skip to content

List Code2WF Generations

Method

This planned API lists scoped Code2WF rows for history, polling, and deferred Figma placement discovery.

HTTP Method

GET: List Code2WF generations

Naming Convention

Query and response fields 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 Code2WF Generations

URI

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

Path Parameters

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

Query Parameters

Name Type Required Description
status string No 0, 1, or 2
pageImportId UUID No Filter by imported page
figmaFileKey string No Filter by target Figma file
materialized boolean No false means materialized_at IS NULL
limit integer No Page size from 1 through 100; default 50, following the current WF2Des list implementation
offset integer No Non-negative row offset; default 0

Deferred placement discovery uses:

?figmaFileKey=aBc1DeFg2HiJ3kLmNoPqRs&status=1&materialized=false&limit=50&offset=0

Response

{
  "code2wfList": [
    {
      "code2wfId": "019ffa75-01c0-75a2-8123-456789abcdf0",
      "organizationId": 1,
      "projectId": 7,
      "pageImportId": "0195f16e-6f11-7ea8-b45c-f6712ed9d8a3",
      "figmaFileKey": "aBc1DeFg2HiJ3kLmNoPqRs",
      "screenId": "AUTORACE_DATABASE",
      "placementTarget": "128:9001",
      "status": "1",
      "attempt": 1,
      "error": null,
      "resultUrl": "1/7/code2wf/019ffa75-01c0-75a2-8123-456789abcdf0/1/result/result.json",
      "flagCount": 0,
      "materializedAt": null,
      "createdAt": "2026-08-13T09:30:00Z",
      "updatedAt": "2026-08-13T09:31:12Z"
    }
  ],
  "total": 1
}

Response Fields

Name Type Description
code2wfList array Code2WF row projections matching the filters.
total integer Full matching-row count before limit / offset.

code2wfList Element Fields

Name Type Description
code2wfId string Job UUID and poll key.
organizationId integer Organization scope.
projectId integer Project scope.
pageImportId string Imported page row ID.
figmaFileKey string Target Figma file.
screenId string Caller-confirmed screen ID.
placementTarget string | null Optional WF2Des-compatible placement node; current-page absolute x/y is used without changing the target.
status string "0" processing, "1" completed, or "2" failed.
attempt integer Always 1 in the MVP.
error string | null Safe failure detail.
resultUrl string | null Client-facing immutable result.json or failed-artifact S3 key.
flagCount integer | null Completion-time count of existing spec outcomes with flagged=true.
materializedAt string | null Figma placement completion timestamp.
createdAt / updatedAt string Audit timestamps (ISO 8601).

Each code2wfList element uses the same row projection as Get Code2WF Status, plus the scoped organization/project IDs like WF2Des list elements. Like the current WF2Des implementation, the endpoint applies a bounded default page and returns the full total. Listing reads PostgreSQL only; it does not read Page Import or S3.

Data Source

All data comes from the backend-owned PostgreSQL code2wf table. The query is scoped by organization/project, excludes soft-deleted rows, and follows the current WF2Des list ordering of created_at DESC. It uses code2wf_org_project_file_status_idx for Figma-file discovery or code2wf_page_import_id_idx for Page Import filtering. No Page Import manifest, S3 result, DocumentDB document, or Figma API is read by this endpoint.

Authentication

Authentication uses an Amazon Cognito JWT. The caller must have Read access to the project.

Error Handling

Description Status Code Status Name
Invalid filter, limit, or offset 400 Bad Request
Missing authentication credentials 401 Unauthorized
Organization, project, or authorized scope not found 404 Not Found
Internal database error 500 Internal Server Error

Processing Flow

  1. Authenticate and verify project Read access.
  2. Validate filters plus limit / offset.
  3. Query scoped, non-deleted PostgreSQL rows and calculate total before applying the page bound.
  4. Return the row projections without S3 hydration.

Deferred Materialization Flow

  1. When the authenticated plugin opens, list the current file with status=1&materialized=false&limit=50&offset=0.
  2. Process the returned rows sequentially. Fetch each immutable result, build a new staging root, and resolve the optional placementTarget through the shared placement path.
  3. Use the existing WF2Des job-ID index and stamp to replace a prior completed root only after the new build succeeds, then call placement with the generated screen's node ID.
  4. Query the same filters with offset=0 again until the page is empty. This is intentional: every successful placement removes a row from the filtered set, so advancing an offset could skip work. total is informational for this flow.
  5. Deduplicate job IDs within the session. A failed row remains unmaterialized and does not stop later rows; a bounded no-progress guard stops repeated failures.
  6. If authentication expires, prompt for login and retry discovery. Never fetch or materialize a row for another Figma file.

There is no server-side materialization claim, lease, status, or retry schedule. Two plugin sessions may discover the same row before either records placement; the job-ID stamp/index and idempotent placement reduce duplicates but are not an atomic cross-session claim. Open-time Code2WF discovery is a planned plugin/API-client extension; it is not part of the current WF2Des plugin.

Detailed Flowchart

flowchart TD
    Start([GET Code2WF List]) --> Auth[Authenticate and Check Read Access]
    Auth --> Validate[Validate Filters Limit Offset]
    Validate --> Query[Query Scoped Non-Deleted Rows]
    Query --> Count[Calculate Total]
    Count --> Page[Apply Limit and Offset]
    Page --> Success[200 code2wfList + total]