Retrieve a single project by its ID. Requires a valid JWT access token. The project must belong to the authenticated user’s tenant.

• The progress field is null when the project status is not BUILDING, and an integer 0-100 when the status is BUILDING.
• The frontend displays different actions depending on the project status:
  • DRAFT or UPDATED — show “Publish” button (triggers build + deploy, handled by a separate conversation/build UC).
  • LIVE — show “Pause” action.
  • PAUSED — show “Resume” action.
  • All non-ARCHIVED statuses — show “Archive” action.
• DRAFT means the project has never been deployed. UPDATED means the project was previously LIVE but has unpublished local changes.

Limitation (MVP): Progress tracking is a stub — the backend always returns 0 for projects in BUILDING status.

sequenceDiagram
    actor User

    User->>+FE: opens project detail

    FE->>+BE: GET /api/v1/projects/{id} <br> Authorization: Bearer {accessToken}

    BE->>BE: validate JWT access token
    alt access token invalid or missing
        BE-->>FE: 401 Unauthorized <br> ErrorResponse
    end

    BE->>DB: find project by id and tenant_id
    alt project not found
        BE-->>FE: 404 Not Found <br> ErrorResponse
    end

    BE->>-FE: 200 OK <br> ProjectResponse

    FE->>-User: display project detail

GET /api/v1/projects/{id} (no request body)

200 OK ProjectResponse:

{
  "data": {
    "id": 1,
    "name": "Wildwood Bakery",
    "description": "Online ordering for a neighborhood bakery",
    "status": "LIVE",
    "url": "wildwood-bakery.talkide.app",
    "accent": "oklch(0.78 0.15 70)",
    "techStack": "Vue + Spring Boot",
    "progress": null,
    "previewUrl": "http://localhost:5201",
    "createdAt": "2026-04-20T10:00:00Z",
    "updatedAt": "2026-04-29T14:30:00Z"
  }
}

401 Unauthorized (missing or invalid access token) ErrorResponse:

{
  "status": 401,
  "code": "AUTHENTICATION_FAILED",
  "message": "Access token is missing or invalid"
}

404 Not Found (project does not exist or does not belong to user’s tenant) ErrorResponse:

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "Project not found"
}

Frontend

Validations

No form inputs — this is a read-only detail view.

Backend

Validations

Test Cases