# ThekedarAI - API Specifications

## Base URL

```
Production: https://api.thekedarai.com/v1
Staging: https://staging-api.thekedarai.com/v1
Development: http://localhost:3000/api/v1
```

---

## Authentication

All authenticated endpoints require a Bearer token in the Authorization header:

```
Authorization: Bearer {token}
```

Token expiry: 7 days

---

## 1. Authentication Endpoints

### 1.1 POST /auth/signup

Create a new user account.

**Request:**

```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123"
}
```

**Validation Rules:**

- `name`: Required, 2-100 characters
- `email`: Required, valid email format, unique
- `password`: Required, minimum 6 characters

**Response (201 Created):**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "user_123abc",
      "name": "John Doe",
      "email": "john@example.com",
      "authProvider": "email",
      "createdAt": "2026-01-30T10:30:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

**Error Responses:**

- `400`: Email already registered
- `400`: Invalid email format
- `400`: Password too short
- `500`: Internal server error

---

### 1.2 POST /auth/login

Login with email and password.

**Request:**

```json
{
  "email": "john@example.com",
  "password": "password123"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "user_123abc",
      "name": "John Doe",
      "email": "john@example.com",
      "authProvider": "email",
      "photoURL": "https://example.com/photo.jpg"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

**Error Responses:**

- `401`: Invalid credentials
- `401`: Please use your social login method
- `500`: Internal server error

---

### 1.3 POST /auth/guest

Create a guest account for anonymous users.

**Request:** (Empty body)

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "guest_456def",
      "name": "Guest User",
      "email": "guest_1738239000@thekedarai.app",
      "authProvider": "guest",
      "createdAt": "2026-01-30T10:30:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

**Notes:**

- Guest users have limited features (3 generations max)
- Auto-generated email format: `guest_{timestamp}@thekedarai.app`

---

### 1.4 GET /auth/profile

Get current user profile.

**Headers:**

```
Authorization: Bearer {token}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "id": "user_123abc",
    "name": "John Doe",
    "email": "john@example.com",
    "authProvider": "email",
    "photoURL": "https://example.com/photo.jpg",
    "createdAt": "2026-01-30T10:30:00Z",
    "stats": {
      "totalDesigns": 25,
      "savedDesigns": 12,
      "generationsRemaining": -1
    }
  }
}
```

**Error Responses:**

- `401`: Missing or invalid token
- `404`: User not found

---

### 1.5 PUT /auth/profile

Update user profile.

**Headers:**

```
Authorization: Bearer {token}
```

**Request:**

```json
{
  "name": "John Updated",
  "photoURL": "https://example.com/new-photo.jpg"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "id": "user_123abc",
    "name": "John Updated",
    "email": "john@example.com",
    "authProvider": "email",
    "photoURL": "https://example.com/new-photo.jpg",
    "createdAt": "2026-01-30T10:30:00Z"
  }
}
```

---

### 1.6 DELETE /auth/account

Delete user account and all associated data.

**Headers:**

```
Authorization: Bearer {token}
```

**Response (200 OK):**

```json
{
  "success": true,
  "message": "Account deleted successfully"
}
```

---

## 2. Design Endpoints

### 2.1 GET /designs/categories

Get available room types, styles, and budget options.

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "roomTypes": [
      {
        "id": "living-room",
        "name": "Living Room",
        "icon": "sofa"
      },
      {
        "id": "bedroom",
        "name": "Bedroom",
        "icon": "bed"
      },
      {
        "id": "kitchen",
        "name": "Kitchen",
        "icon": "utensils"
      },
      {
        "id": "bathroom",
        "name": "Bathroom",
        "icon": "bath"
      },
      {
        "id": "dining",
        "name": "Dining Room",
        "icon": "dining"
      },
      {
        "id": "office",
        "name": "Home Office",
        "icon": "briefcase"
      },
      {
        "id": "outdoor",
        "name": "Outdoor/Garden",
        "icon": "tree"
      }
    ],
    "styles": [
      {
        "id": "modern",
        "name": "Modern",
        "description": "Clean lines, minimalist furniture, neutral colors"
      },
      {
        "id": "minimalist",
        "name": "Minimalist",
        "description": "Less is more, functional, clutter-free"
      },
      {
        "id": "traditional",
        "name": "Traditional",
        "description": "Classic, ornate details, rich colors"
      },
      {
        "id": "contemporary",
        "name": "Contemporary",
        "description": "Current trends, bold colors, mixed materials"
      },
      {
        "id": "industrial",
        "name": "Industrial",
        "description": "Exposed brick, metal, raw materials"
      },
      {
        "id": "scandinavian",
        "name": "Scandinavian",
        "description": "Light, airy, functional, cozy"
      }
    ],
    "budgets": [
      {
        "id": "budget",
        "name": "Budget",
        "symbol": "₹",
        "description": "Cost-effective materials, standard finishes",
        "priceRange": "₹800-1,200 per sq.m"
      },
      {
        "id": "standard",
        "name": "Standard",
        "symbol": "₹₹",
        "description": "Quality materials, good finishes",
        "priceRange": "₹1,200-2,000 per sq.m"
      },
      {
        "id": "premium",
        "name": "Premium",
        "symbol": "₹₹₹",
        "description": "Luxury materials, designer finishes",
        "priceRange": "₹2,000-3,500 per sq.m"
      }
    ]
  }
}
```

---

### 2.2 POST /designs/upload

Upload image to start design process.

**Headers:**

```
Authorization: Bearer {token}
Content-Type: multipart/form-data
```

**Request (Form Data):**

```
image: (file) - JPEG/PNG/WEBP, max 10MB
roomType: "living-room"
style: "modern"
budget: "standard"
```

**Response (201 Created):**

```json
{
  "success": true,
  "data": {
    "id": "design_789xyz",
    "designId": "design_789xyz",
    "status": "pending",
    "roomType": "living-room",
    "style": "modern",
    "budget": "standard",
    "originalImage": "https://storage.thekedarai.com/uploads/original/1738239000_abc123.jpg",
    "estimatedCost": {
      "min": 15000,
      "max": 25000,
      "currency": "INR"
    },
    "createdAt": "2026-01-30T10:30:00Z"
  }
}
```

**Error Responses:**

- `400`: Image file required
- `400`: File too large (max 10MB)
- `400`: Invalid file type (only JPEG, PNG, WEBP)
- `401`: Unauthorized
- `403`: Generation limit reached (guest users)

---

### 2.3 POST /designs/generate

Trigger AI design generation.

**Headers:**

```
Authorization: Bearer {token}
Content-Type: application/json
```

**Request:**

```json
{
  "designId": "design_789xyz"
}
```

**Response (202 Accepted):**

```json
{
  "success": true,
  "data": {
    "id": "design_789xyz",
    "status": "processing",
    "message": "AI generation started",
    "estimatedTime": 45
  }
}
```

**Error Responses:**

- `404`: Design not found
- `400`: Design already generated
- `500`: AI service error

---

### 2.4 GET /designs/{id}/status

Poll generation status.

**Headers:**

```
Authorization: Bearer {token}
```

**Response (200 OK) - Processing:**

```json
{
  "success": true,
  "data": {
    "id": "design_789xyz",
    "status": "processing",
    "progress": 65,
    "message": "Generating design..."
  }
}
```

**Response (200 OK) - Completed:**

```json
{
  "success": true,
  "data": {
    "id": "design_789xyz",
    "status": "completed",
    "progress": 100,
    "generatedImage": "https://storage.thekedarai.com/uploads/generated/1738239100_xyz789.jpg",
    "completedAt": "2026-01-30T10:31:30Z"
  }
}
```

**Response (200 OK) - Failed:**

```json
{
  "success": true,
  "data": {
    "id": "design_789xyz",
    "status": "failed",
    "error": "AI generation timeout",
    "message": "Please try again"
  }
}
```

---

### 2.5 GET /designs/{id}

Get single design details.

**Headers:**

```
Authorization: Bearer {token}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "id": "design_789xyz",
    "roomType": "living-room",
    "style": "modern",
    "budget": "standard",
    "originalImage": "https://storage.thekedarai.com/uploads/original/1738239000_abc123.jpg",
    "generatedImage": "https://storage.thekedarai.com/uploads/generated/1738239100_xyz789.jpg",
    "status": "completed",
    "estimatedCost": {
      "min": 15000,
      "max": 25000,
      "currency": "INR",
      "breakdown": {
        "basePerSqm": 1200,
        "roomSize": 12,
        "budgetMultiplier": 1.0,
        "roomMultiplier": 1.0,
        "cityMultiplier": 1.0
      }
    },
    "suggestedMaterials": [
      "Vitrified Tiles",
      "Laminate Flooring",
      "Standard Paint",
      "Good Quality Fixtures"
    ],
    "metadata": {
      "roomSize": 12,
      "city": "tier2"
    },
    "createdAt": "2026-01-30T10:30:00Z",
    "completedAt": "2026-01-30T10:31:30Z",
    "saved": true
  }
}
```

**Error Responses:**

- `404`: Design not found
- `401`: Unauthorized

---

### 2.6 GET /designs

List user's designs with pagination.

**Headers:**

```
Authorization: Bearer {token}
```

**Query Parameters:**

- `page`: Page number (default: 1)
- `limit`: Items per page (default: 20, max: 100)
- `status`: Filter by status (pending, processing, completed, failed)
- `roomType`: Filter by room type
- `style`: Filter by style
- `sortBy`: Sort field (createdAt, completedAt)
- `sortOrder`: Sort order (asc, desc)

**Example:**

```
GET /designs?page=1&limit=20&status=completed&sortBy=createdAt&sortOrder=desc
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "designs": [
      {
        "id": "design_789xyz",
        "roomType": "living-room",
        "style": "modern",
        "budget": "standard",
        "originalImage": "https://storage.thekedarai.com/uploads/original/...",
        "generatedImage": "https://storage.thekedarai.com/uploads/generated/...",
        "status": "completed",
        "estimatedCost": {
          "min": 15000,
          "max": 25000,
          "currency": "INR"
        },
        "createdAt": "2026-01-30T10:30:00Z",
        "saved": true
      }
      // ... more designs
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}
```

---

### 2.7 POST /designs/{id}/save

Save design to favorites.

**Headers:**

```
Authorization: Bearer {token}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "id": "design_789xyz",
    "saved": true,
    "message": "Design saved successfully"
  }
}
```

---

### 2.8 DELETE /designs/{id}

Delete a design and associated images.

**Headers:**

```
Authorization: Bearer {token}
```

**Response (200 OK):**

```json
{
  "success": true,
  "message": "Design deleted successfully"
}
```

**Error Responses:**

- `404`: Design not found
- `403`: Not authorized to delete this design

---

### 2.9 POST /designs/estimate-cost

Get cost estimate without AI generation.

**Headers:**

```
Authorization: Bearer {token}
Content-Type: application/json
```

**Request:**

```json
{
  "roomType": "living-room",
  "budget": "premium",
  "roomSize": 15.5,
  "city": "tier1"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "estimatedCost": {
      "min": 35000,
      "max": 55000,
      "currency": "INR"
    },
    "breakdown": {
      "basePerSqm": 1200,
      "roomSize": 15.5,
      "budgetMultiplier": 1.8,
      "roomMultiplier": 1.0,
      "cityMultiplier": 1.3
    },
    "suggestedMaterials": [
      "Italian Marble",
      "Teak Wood",
      "Designer Tiles",
      "Premium Paint",
      "Luxury Fixtures"
    ]
  }
}
```

---

## 3. Error Response Format

All error responses follow this structure:

```json
{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    // Optional additional error details
  }
}
```

### Common Error Codes

- `AUTH_REQUIRED`: Authentication required
- `INVALID_TOKEN`: Token expired or invalid
- `VALIDATION_ERROR`: Request validation failed
- `NOT_FOUND`: Resource not found
- `FORBIDDEN`: Action not allowed
- `RATE_LIMIT_EXCEEDED`: Too many requests
- `FILE_TOO_LARGE`: File exceeds size limit
- `INVALID_FILE_TYPE`: Unsupported file type
- `AI_SERVICE_ERROR`: AI generation failed
- `INTERNAL_ERROR`: Server error

---

## 4. Rate Limiting

**Free Users (Guest & Registered):**

- 100 requests per 15 minutes
- 3 AI generations per day (guest users)
- 20 AI generations per day (registered free users)

**Headers Returned:**

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1738239900
```

**Rate Limit Error (429):**

```json
{
  "success": false,
  "error": "Rate limit exceeded. Try again in 5 minutes.",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "retryAfter": 300
  }
}
```

---

## 5. Webhooks (Future)

### Design Completed Webhook

Notify client when AI generation completes.

**Endpoint:** Client-provided URL  
**Method:** POST  
**Payload:**

```json
{
  "event": "design.completed",
  "data": {
    "designId": "design_789xyz",
    "status": "completed",
    "generatedImage": "https://storage.thekedarai.com/...",
    "userId": "user_123abc",
    "timestamp": "2026-01-30T10:31:30Z"
  }
}
```

---

## 6. SDK Examples (Future)

### JavaScript/TypeScript

```typescript
import { ThekedarAI } from "@thekedarai/sdk";

const client = new ThekedarAI({
  apiKey: process.env.THEKEDAR_API_KEY,
});

// Upload and generate
const design = await client.designs.create({
  image: fileBlob,
  roomType: "living-room",
  style: "modern",
  budget: "standard",
});

// Poll for completion
const completed = await client.designs.waitForCompletion(design.id);
console.log(completed.generatedImage);
```

---

**API Version:** v1  
**Last Updated:** January 2026  
**Status:** ✅ MVP Specification Complete