Get Des2Code

Method

REST method is adopted.

HTTP Method

GET: Get des2code results

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 (temporary Bearer token)
• Content-Type
• Accept
• Accept-language

Response Headers

• Content-Type

Get Des2Code Results

URI

GET /v1/des2code/{design_id}

Path Parameters

Name	Type	Required	Description
design_id	string	Required	Design ID (format: {project_id}_{file_id}_{node_id})

Response

The response is JSON.

{
  "designId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "matchedCodeCount": 2,
  "matchedCodes": [
    {
      "codeId": "0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b",
      "name": "Button Primary",
      "semanticValue": ["button", "primary", "cta"],
      "similarity": 0.92,
      "visualSimilarity": 0.95,
      "semanticSimilarity": 0.89,
      "sourceCode": "export function ButtonPrimary() { ... }",
      "cssCode": ".buttonPrimary { ... }"
    },
    {
      "codeId": "1192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6c",
      "name": "Primary Button",
      "semanticValue": ["button", "submit"],
      "similarity": 0.87,
      "visualSimilarity": 0.82,
      "semanticSimilarity": 0.91,
      "sourceCode": "export function PrimaryButton() { ... }",
      "cssCode": ".primaryButton { ... }"
    }
  ],
  "artifact": {
    "bucket": "dev-guinness-backend",
    "key": "1/42/des2code/42_hDDA9BNori9OTXSClduXqR_40002029%3A37033-20260628T000000000000Z-result.json",
    "contentType": "application/json",
    "expiresAt": "2026-07-28T00:00:00Z"
  },
  "status": "success",
  "processedAt": 1234567890000
}

Match Status

Status	Description
pending	Des2Code request is queued but not yet processed
processing	Des2Code is currently processing
success	Des2Code completed successfully
failed	Des2Code failed (check error message)

Response Fields

Name	Type	Description
designId	string	Design ID
matchedCodeCount	number	Number of matched code entries
matchedCodes	array	Array of matched code entries
matchedCodes[].codeId	string	Matched code ID
matchedCodes[].name	string	Matched code name
matchedCodes[].semanticValue	string[]	Matched code semantic words
matchedCodes[].similarity	number	Weighted raw score
matchedCodes[].visualSimilarity	number | null	Raw visual similarity score
matchedCodes[].semanticSimilarity	number | null	Raw semantic similarity score
matchedCodes[].sourceCode	string | null	Matched code source code for assistant context
matchedCodes[].cssCode	string | null	Matched code CSS for assistant context
artifact	object | null	Latest S3 result artifact reference
status	string	Des2Code status
processedAt	number	Processing timestamp (epoch milliseconds)

Authentication

This endpoint uses a temporary Bearer token (not a standard JWT).

Authorization: Bearer <temporary_token>

Error Handling

The status codes for error handling are as follows.

Description	Status Code	Status Name
Temporary token missing or invalid	401	Unauthorized
Design not found or des2code results unavailable	404	Not Found
Internal server error	500	Internal Server Error

Processing Flow

1. Extract design ID from path parameters
2. Query the PostgreSQL latest Des2Code result/status and artifact reference written by the AI status webhook
3. Return des2code results with similarity scores and the latest S3 artifact reference

Detailed Flowchart

flowchart TD
    Start([GET Request]) --> Auth[Auth & Parameter Extraction]
    Auth --> Service[Service Layer]
    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Read permission?}
    HasAccess -->|No| Err404[404 Not Found]
    HasAccess -->|Yes| QueryDB[Repository Layer]
    QueryDB --> FindRecord[Fetch latest Des2Code result + artifact ref<br/>WHERE deletedAt IS NULL]
    FindRecord --> Exists{Exists?}
    Exists -->|No| Err404
    Exists -->|Yes| Format[Format Response]
    Format --> Success[200 OK]

Similarity Scores

Matches include weighted and raw similarity scores:

Field	Description
similarity	Weighted raw score used for ranking
visualSimilarity	Raw visual score, 0.0 to 1.0, or null when visual search is disabled
semanticSimilarity	Raw semantic score, 0.0 to 1.0, or null when semantic search is disabled

Polling Recommendation

Clients may periodically poll this endpoint to check for completion of the des2code process. Completion is driven by guinness-ai-v2/apps/des2code writing an S3 artifact and posting POST /v1/webhooks/ai-status, after which the backend updates PostgreSQL. Use exponential backoff while status is pending or processing.