Create Design

Method

REST method is adopted.

HTTP Method

POST: Create design (import from Figma URL)

Naming Convention

To unify the naming of query parameters and nodes and improve readability, snake_case is used for URIs and JSON nodes in requests.

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

Create Design

URI

POST /v1/organizations/{organization_id}/projects/{project_id}/designs

Path Parameters

Name	Type	Required	Description
organization_id	number	Required	Backend PostgreSQL organization ID
project_id	number	Required	Backend PostgreSQL project ID

Request Body

The request body is JSON.

{
  "figma_url": "https://www.figma.com/file/ABC123/Design-File?node-id=2585:942"
}

Request Parameters

Name	Type	Required	Description
figma_url	string	Required	Figma URL (file or design)

Response

The response is JSON (HTTP status: 201 Created).

{
  "id": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "projectId": 42,
  "s3Key": null,
  "frameName": null,
  "status": 0,
  "createdAt": 1234567890000,
  "updatedAt": 1234567890000,
  "deletedAt": null,
  "createdBy": "user-id",
  "updatedBy": "user-id",
  "deletedBy": null
}

Status Values

Value	Description
0	Pending
1	Processing
2	Completed
3	Failed

Response Fields

Name	Type	Description
id	string	Design ID (format: {project_id}_{file_id}_{node_id})
projectId	number	Backend PostgreSQL project ID
s3Key	string | null	S3 object key (set after processing)
frameName	string | null	Figma frame name (set after processing)
status	number	Processing status (0-3)
createdAt	number	Creation timestamp (epoch milliseconds)
updatedAt	number	Update timestamp (epoch milliseconds)

Authentication

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

Error Handling

The status codes for error handling are as follows.

Description	Status Code	Status Name
Invalid Figma URL format	400	Bad Request
Missing credentials	401	Unauthorized
Insufficient permissions	403	Forbidden
Project or organization not found	404	Not Found
Project codebase index is not completed	409	Conflict
Internal server error	500	Internal Server Error

Processing Flow

1. Parse Figma URL to extract fileId and nodeId
2. Read the project's dedicated codebase_index row, require completed, and resolve the stable codebase_index_url
3. Retrieve the user's Figma PAT
4. Fetch design data and image from Figma API (parallel)
5. Upload image and required JSON schema to S3 (parallel)
6. Create the design row and derive sortable source_order from its authoritative source timestamp plus the request token
7. Send design-import to SQS with organization_id, project_id, design_id, design_name, file_id, node_id, img_url, required json_schema_url, source_order, and stable codebase_index_url; do not include figma_url or an expected bundle token/hash
8. Return response with initial status 0 (pending)

Detailed Flowchart

flowchart TD
    Start([POST Request]) --> Route[Route Handler]
    Route --> Auth[Auth & Parameter Extraction]
    Auth --> Service[Service Layer]

    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Write permission?}
    HasAccess -->|No| Err404[404 Not Found]
    HasAccess -->|Yes| ParseURL[Parse Figma URL]

    ParseURL --> ValidURL{Valid URL?}
    ValidURL -->|NG| Err400[400 Bad Request]
    ValidURL -->|OK| CheckIndex[Read dedicated codebase_index]

    CheckIndex --> IndexReady{Completed with current URL?}
    IndexReady -->|No| Err409[409 CODEBASE_INDEX_NOT_READY]
    IndexReady -->|Yes| GetToken[Get Figma PAT]

    GetToken --> HasToken{Token exists?}
    HasToken -->|No| Err400
    HasToken -->|Yes| ParallelFetch[Parallel Figma API Calls]

    ParallelFetch --> FetchImage[Fetch Figma Image]
    ParallelFetch --> FetchSchema[Fetch Design Data]

    FetchImage --> ParallelS3[Parallel S3 Uploads]
    FetchSchema --> ParallelS3

    ParallelS3 --> UploadImage[Upload Image]
    ParallelS3 --> UploadJSON[Upload JSON]

    UploadImage --> CheckUploads{Upload successful?}
    UploadJSON --> CheckUploads

    CheckUploads -->|NG| Err500[500 Internal Error]
    CheckUploads -->|OK| CreateDB[Create DB Record<br/>status=0 pending + source_order]

    CreateDB --> SQSSend[Send SQS Message<br/>with codebase_index_url]

    SQSSend --> SQSOK{Successful?}
    SQSOK -->|NG| Err500
    SQSOK -->|OK| Success[201 Created<br/>Async processing started]

Async Processing

Designs are processed asynchronously. Background workers update the status: - 0 (pending) → 1 (processing) → 2 (completed) or 3 (failed)

Figma URL Format

Valid Figma URL formats: - https://www.figma.com/file/{fileId}/{fileName}?node-id={nodeId} - https://www.figma.com/design/{fileId}/{fileName}?node-id={nodeId}

The design ID will be in the format {project_id}_{file_id}_{node_id} (e.g., 42_hDDA9BNori9OTXSClduXqR_40002029:37033). It includes the Figma node ID.