Skip to content

Create Des2Code

Method

REST method is adopted.

HTTP Method

POST: Trigger a Des2Code request

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

Response Headers

  • Content-Type

Des2Code Request

URI

POST /v1/des2code

Request Body

The request body is JSON and strict.

{
  "design_id": "42_hDDA9BNori9OTXSClduXqR_40002029:37033"
}

Request Parameters

Name Type Required Description
design_id string Required Design ID, 1-500 characters; only alphanumeric, _, :, and -

The request accepts no project/organization override, model, prompt, index ID, or matching bound. The backend resolves organization/project from the authorized PostgreSQL design row. Unknown body fields are rejected.

Response

The response is JSON (HTTP status: 202 Accepted).

{
  "message": "Des2Code request queued successfully",
  "designId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "requestId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"
}

Response Fields

Name Type Description
message string Queue acknowledgement
designId string Authorized design ID
requestId string UUIDv7 correlation/artifact identity

Authentication

This endpoint uses the protected user route and verifies the Bearer session token. The authenticated subject must be authorized for the design's project.

Authorization: Bearer <session_token>

Error Handling

The status codes for error handling are as follows.

Description Status Code Status Name
Invalid design ID/body or missing required field 400 Bad Request
Bearer token missing or invalid 401 Unauthorized
Design not found or not visible to the user 404 Not Found
Design import is not completed 409 Conflict (DESIGN_IMPORT_NOT_READY)
AI-v2 current code_index is missing or not ready 409 Conflict (CODE_INDEX_NOT_READY)
Internal server error 500 Internal Server Error
SQS infrastructure unavailable 503 Service Unavailable

Processing Flow

  1. Validate the strict design_id request body.
  2. Load the PostgreSQL design with project/organization and enforce user access.
  3. Require the design status to be completed.
  4. Read AI-v2 GET /internal/projects/{project_id}/code-index with organization scope and require the returned current DocumentDB index to be ready.
  5. Generate a UUIDv7 requestId.
  6. Send a flat des2code SQS message containing design_id, project_id, organization_id, and request_id.
  7. Require a non-empty SQS message ID and return 202 Accepted.

Detailed Flowchart

flowchart TD
    Start([POST /v1/des2code]) --> Route[Route Handler]
    Route --> ValidateToken[Verify Bearer session]

    ValidateToken --> TokenValid{Valid?}
    TokenValid -->|NG| Err401[401 Unauthorized]
    TokenValid -->|OK| ExtractDesignId[Validate strict design_id]

    ExtractDesignId --> ValidateFormat{Format valid?}
    ValidateFormat -->|NG| Err400[400 Bad Request]
    ValidateFormat -->|OK| CheckDesign[Load design + project scope]

    CheckDesign --> DesignExists{Exists and authorized?}
    DesignExists -->|No| Err404[404 Not Found]
    DesignExists -->|Yes| DesignReady{Design completed?}
    DesignReady -->|No| Err409Design[409 DESIGN_IMPORT_NOT_READY]
    DesignReady -->|Yes| CheckIndex[Read AI-v2 current code_index]
    CheckIndex --> IndexReady{status = ready?}
    IndexReady -->|No| Err409Index[409 CODE_INDEX_NOT_READY]
    IndexReady -->|Yes| GenerateRequestId[Generate UUIDv7 requestId]

    GenerateRequestId --> SQSSend[Send flat des2code SQS message]
    SQSSend --> SQSOK{MessageId present?}
    SQSOK -->|NG| Err503[503 Service Unavailable]
    SQSOK -->|OK| Success[202 Accepted]

Async Processing

This endpoint only queues work. The worker writes success to {organization_id}/{project_id}/des2code/{design_id}/{request_id}.json or failure to the same filename with -failed, then posts the backend AI-status webhook. The webhook validates the design scope and logs the event; it does not create/update a Des2Code PostgreSQL run row.

Each trigger receives a new request ID. SQS retries of that trigger reuse its artifact key. Clients poll GET, which lists the authorized design prefix and returns the newest contract-valid request artifact.

SQS Error Handling

If SQS sending fails or returns no MessageId, the request fails before a 202 acknowledgement. The backend logs the sanitized design ID and request ID and maps queue unavailability to the service error response.