Get Project

Overview

Retrieves detailed information about a specific project, including all image generations, version history, and processing status. This endpoint returns both the project metadata and all images that have been processed within the project.

Authentication

Requires an authenticated user session. Users can only access projects within their workspace.

Path Parameters

string

required

The unique project identifier (UUID format).Example: a1b2c3d4-5678-90ab-cdef-1234567890ab

Request Example

GET /api/projects/a1b2c3d4-5678-90ab-cdef-1234567890ab

Response

Returns a project object with nested images array.

project

object

required

The project object.

project.id

string

required

Unique project identifier (UUID format).

project.workspaceId

string

required

The workspace ID this project belongs to.

project.userId

string

required

The ID of the user who created the project.

project.name

string

required

The project name.

project.styleTemplateId

string

required

The style template ID applied to images in this project.

project.roomType

string | null

The room type classification (e.g., living-room, bedroom, kitchen).

project.thumbnailUrl

string | null

URL to the project thumbnail image.

project.status

string

required

Current project status: pending, processing, completed, or failed.

project.imageCount

number

required

Total number of images in the project (including all versions).

project.completedCount

number

required

Number of successfully processed images.

project.createdAt

string

required

ISO 8601 timestamp when the project was created.

project.updatedAt

string

required

ISO 8601 timestamp when the project was last updated.

images

array

required

Array of image generation objects, ordered by creation date (newest first).

images[].id

string

required

Unique image generation identifier (UUID).

images[].workspaceId

string

required

The workspace ID.

images[].userId

string

required

The ID of the user who created this image generation.

images[].projectId

string

required

The parent project ID.

images[].originalImageUrl

string

required

URL to the original uploaded image before AI processing.

images[].resultImageUrl

string | null

URL to the AI-generated result image. null if still processing or failed.

images[].prompt

string

required

The AI prompt used for image generation. Typically combines the style template with room-specific instructions.

images[].version

number

required

Version number for edit history tracking. Starts at 1 for original, increments for each edit.

images[].parentId

string | null

The ID of the root image in the version chain. null for root images (version 1).

images[].status

string

required

Processing status of this image.Values:

pending - Queued for processing
processing - Currently being processed by AI
completed - Successfully processed
failed - Processing failed

images[].errorMessage

string | null

Error message if status is failed.

images[].metadata

object | null

Additional metadata about the generation (model used, processing time, cost, etc.).

images[].createdAt

string

required

ISO 8601 timestamp when the image was uploaded.

images[].updatedAt

string

required

ISO 8601 timestamp when the image status was last updated.

Success Response Example

{
  "project": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "workspaceId": "ws_abc123",
    "userId": "user_xyz789",
    "name": "Sunset Villa - Master Bedroom",
    "styleTemplateId": "modern-scandinavian",
    "roomType": "bedroom",
    "thumbnailUrl": "https://storage.example.com/thumbnails/abc123.jpg",
    "status": "completed",
    "imageCount": 3,
    "completedCount": 3,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T11:45:00.000Z"
  },
  "images": [
    {
      "id": "img_001",
      "workspaceId": "ws_abc123",
      "userId": "user_xyz789",
      "projectId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "originalImageUrl": "https://storage.example.com/originals/photo1.jpg",
      "resultImageUrl": "https://storage.example.com/results/photo1_edited.jpg",
      "prompt": "Modern Scandinavian bedroom with warm natural light, minimalist furniture, and neutral tones",
      "version": 1,
      "parentId": null,
      "status": "completed",
      "errorMessage": null,
      "metadata": {
        "model": "flux-pro/v1.1",
        "processingTime": 12.5,
        "cost": 0.05
      },
      "createdAt": "2024-01-15T10:35:00.000Z",
      "updatedAt": "2024-01-15T10:35:15.000Z"
    },
    {
      "id": "img_002",
      "workspaceId": "ws_abc123",
      "userId": "user_xyz789",
      "projectId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "originalImageUrl": "https://storage.example.com/results/photo1_edited.jpg",
      "resultImageUrl": "https://storage.example.com/results/photo1_edited_v2.jpg",
      "prompt": "Modern Scandinavian bedroom with warmer lighting and added decorative pillows",
      "version": 2,
      "parentId": "img_001",
      "status": "completed",
      "errorMessage": null,
      "metadata": {
        "model": "flux-pro/v1.1",
        "processingTime": 11.8,
        "cost": 0.05
      },
      "createdAt": "2024-01-15T11:20:00.000Z",
      "updatedAt": "2024-01-15T11:20:12.000Z"
    }
  ]
}

Error Response - Project Not Found

null

If the project doesn’t exist or doesn’t belong to the user’s workspace, the endpoint returns null.

Implementation Details

Access Control

The endpoint performs workspace-based authorization:

Authenticates the user session
Retrieves user’s workspace ID
Fetches project and verifies project.workspaceId matches user’s workspace
Returns null if workspace mismatch or project not found

This ensures users can only access projects within their workspace, providing workspace-level isolation.

Version History

Images support version tracking for edit history:

Root Image (version 1): Original upload with parentId = null
Edited Versions (version 2+): Re-processed images with parentId pointing to the root

All versions share the same parentId, creating a version chain:

Root Image (v1, parentId=null)
  ├─ Edit v2 (parentId → Root)
  ├─ Edit v3 (parentId → Root)
  └─ Edit v4 (parentId → Root)

Database Query

The endpoint executes two queries:

-- Get project
SELECT * FROM project WHERE id = $projectId LIMIT 1;

-- Get all images for project (ordered newest first)
SELECT * FROM image_generation
WHERE project_id = $projectId
ORDER BY created_at DESC;

Image Status Updates

When images complete processing, the project’s completedCount and status are automatically updated:

Trigger: Image status changes to completed
Action: Calls updateProjectCounts(projectId) to recalculate
Side Effect: May create invoice line item on first completed image

Payment Integration

Projects require payment before AI processing begins:

Invoice-eligible workspaces: Automatically billed via invoice
Other workspaces: Require Stripe checkout completion
Payment status: Checked via getProjectPaymentStatus(projectId)

Payment is handled separately from project creation - see /lib/actions/payments.ts.

Create project: See Create Project
List projects: See List Projects
Process image: POST /api/process-image
Download all images: GET /api/download/:projectId

Source Code Reference

Implemented in:

Page Component: /app/dashboard/[id]/page.tsx:ProjectDetailPage (lines 15-85)
Database Query: /lib/db/queries.ts:getProjectById (lines 307-331)
Schema: /lib/db/schema.ts (project: lines 164-196, imageGeneration: lines 202-241)

Authentication

Projects

Images

Videos

Overview

Authentication

Path Parameters

Request Example

Response

Success Response Example

Error Response - Project Not Found

Implementation Details

Access Control

Version History

Database Query

Image Status Updates

Payment Integration

Source Code Reference

Build docs developers (and LLMs) love

Authentication

Projects

Images

Videos

​Overview

​Authentication

​Path Parameters

​Request Example

​Response

​Success Response Example

​Error Response - Project Not Found

​Implementation Details

​Access Control

​Version History

​Database Query

​Image Status Updates

​Payment Integration

​Related Endpoints

​Source Code Reference

Build docs developers (and LLMs) love

Overview

Authentication

Path Parameters

Request Example

Response

Success Response Example

Error Response - Project Not Found

Implementation Details

Access Control

Version History

Database Query

Image Status Updates

Payment Integration

Related Endpoints

Source Code Reference