Skip to content

Record Code2WF Placement

Method

This planned API follows the existing WF2Des row-level placement convention. The plugin calls it after building the native Figma screen; the backend stamps only materialized_at.

HTTP Method

POST: Record Code2WF placement

Naming Convention

Request and response JSON 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

Record Code2WF Placement

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/code2wf/{code2wf_id}/placement

Path Parameters

Name Type Required Description
organization_id integer Required Organization ID
project_id integer Required Project ID
code2wf_id string Required Code2WF UUID

Request Body

{
  "placedNodeId": "1204:57"
}

Request Parameters

Name Type Required Description
placedNodeId string Required Figma node ID of the generated screen; echoed in the response and not stored on the PostgreSQL row.

Response

{
  "projectId": "7",
  "code2wfId": "019ffa75-01c0-75a2-8123-456789abcdf0",
  "status": "1",
  "placedNodeId": "1204:57",
  "materializedAt": "2026-08-13T09:35:00Z"
}

Response Fields

Name Type Description
projectId string Project scope, serialized like the existing WF2Des placement response.
code2wfId string Code2WF job UUID.
status string Completed status, "1".
placedNodeId string Figma node ID supplied by the plugin and echoed without persistence.
materializedAt string Placement completion timestamp (ISO 8601).

A repeated call after materializedAt is set returns 200 OK with the existing timestamp. It does not stamp the row again. As with WF2Des, the repeated request's node ID is only echoed; PostgreSQL does not store it.

Status Codes

Value Meaning
"1" completed and eligible for placement

Statuses "0" and "2" are not eligible and are returned through the not-found surface, matching WF2Des placement behavior.

Authentication

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

Error Handling

Description Status Code Status Name
Invalid placedNodeId 400 Bad Request
Missing authentication credentials 401 Unauthorized
Project scope or job is unknown, unauthorized, soft-deleted, processing, or failed 404 Not Found
Database update fails 500 Internal Server Error

Processing Flow

  1. Authenticate and verify Write access.
  2. Fetch the scoped, non-deleted Code2WF row.
  3. Require status="1".
  4. If materialized_at is already set, return it without a write.
  5. Otherwise set materialized_at, updated_at, and updated_by in one backend transaction.
  6. Return the timestamp and echo placedNodeId.

No SQS message is sent. The endpoint does not store additional materialization states, reports, child-node IDs, or Figma page IDs. The planned Code2WF plugin path owns rebuild and uses the existing WF2Des stamp/index to swap a completed replacement for prior output.

Detailed Flowchart

flowchart TD
    Start([POST Code2WF Placement]) --> Auth[Authenticate and Check Write Access]
    Auth --> Row[Fetch Scoped Completed Row]
    Row --> Placed{materialized_at exists?}
    Placed -->|Yes| Existing[200 Existing Timestamp]
    Placed -->|No| Stamp[Set materialized_at + Audit Fields]
    Stamp --> Success[200 Placement]