# Properties API Documentation

## 📚 Complete Guide to Houses & Cars API

This documentation covers all property endpoints with real curl examples and expected responses.

---

## 🔑 Authentication & Roles

### User Roles

| Role | Can Create Properties | Can View Properties | Can Edit Own Properties |
|------|----------------------|-------------------|------------------------|
| **customer** | ❌ No | ✅ Yes (public) | N/A |
| **owner** | ✅ Yes | ✅ Yes (all) | ✅ Yes |
| **admin** | ✅ Yes | ✅ Yes (all) | ✅ Yes (all properties) |

### Authentication Headers

All protected endpoints require:
```bash
Authorization: Bearer <access_token>
```

Get your token by logging in:
```bash
curl -X POST http://localhost:5000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email_or_username": "owner@example.com",
    "password": "password123"
  }'
```

---

## 📤 Image Upload Workflow

### Step 1: Upload Images First

Before creating a property, upload images to get URLs.

#### Upload House Images

**Endpoint:** `POST /uploads/house-images`  
**Auth:** Owner or Admin role required  
**Rate Limit:** 20 per hour  
**Content-Type:** multipart/form-data

**Request:**
```bash
curl -X POST http://localhost:5000/uploads/house-images \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -F "images=@/path/to/villa-front.jpg" \
  -F "images=@/path/to/villa-living.jpg" \
  -F "images=@/path/to/villa-pool.jpg"
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Uploaded 3 of 3 images",
  "data": {
    "images": [
      {
        "image_url": "/static/uploads/houses/a1b2c3d4_0_abc12345.jpg",
        "display_order": 0
      },
      {
        "image_url": "/static/uploads/houses/a1b2c3d4_1_def67890.jpg",
        "display_order": 1
      },
      {
        "image_url": "/static/uploads/houses/a1b2c3d4_2_ghi13579.jpg",
        "display_order": 2
      }
    ],
    "errors": []
  }
}
```

**Error Response (400 Bad Request):**
```json
{
  "success": false,
  "message": "Maximum 10 images allowed per upload",
  "data": null
}
```

#### Upload Car Images

**Endpoint:** `POST /uploads/car-images`  
**Same format as house images**

**Request:**
```bash
curl -X POST http://localhost:5000/uploads/car-images \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -F "images=@/path/to/car-front.jpg" \
  -F "images=@/path/to/car-interior.jpg"
```

---

## 🏠 HOUSE ENDPOINTS

### 1. List All Houses (Public)

**Endpoint:** `GET /houses`  
**Auth:** None (Public)  
**Rate Limit:** 100 per hour

**Query Parameters:**
- `city` - Filter by city (case-insensitive)
- `country` - Filter by country
- `category` - Filter by category (Villa, Apartment, Studio, etc.)
- `min_price` - Minimum price per day
- `max_price` - Maximum price per day
- `bedrooms` - Minimum bedrooms
- `max_guests` - Minimum guest capacity
- `page` - Page number (default: 1)
- `per_page` - Items per page (default: 20, max: 100)

**Example 1: Basic listing**
```bash
curl http://localhost:5000/houses
```

**Example 2: Filter by city and price**
```bash
curl "http://localhost:5000/houses?city=Miami&min_price=100&max_price=500"
```

**Example 3: With pagination**
```bash
curl "http://localhost:5000/houses?city=Miami&bedrooms=3&page=1&per_page=10"
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "houses": [
      {
        "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "title": "Luxury Beachfront Villa",
        "category": "Villa",
        "price_per_day": 250.00,
        "price_per_week": 1500.00,
        "price_per_month": 5000.00,
        "currency": "USD",
        "city": "Miami",
        "country": "USA",
        "bedrooms": 4,
        "bathrooms": 3,
        "max_guests": 8,
        "rating_average": 4.8,
        "review_count": 24,
        "is_available": true,
        "primary_image": "/static/uploads/houses/a1b2c3d4_0_abc12345.jpg"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
        "title": "Modern Downtown Apartment",
        "category": "Apartment",
        "price_per_day": 120.00,
        "price_per_week": 700.00,
        "price_per_month": 2500.00,
        "currency": "USD",
        "city": "Miami",
        "country": "USA",
        "bedrooms": 2,
        "bathrooms": 2,
        "max_guests": 4,
        "rating_average": 4.5,
        "review_count": 18,
        "is_available": true,
        "primary_image": "/static/uploads/houses/b2c3d4e5_0_def67890.jpg"
      }
    ],
    "total": 47,
    "page": 1,
    "per_page": 20,
    "pages": 3,
    "has_next": true,
    "has_prev": false
  }
}
```

---

### 2. Get Single House (Public)

**Endpoint:** `GET /houses/<house_id>`  
**Auth:** None (Public)  
**Rate Limit:** 100 per hour

**Request:**
```bash
curl http://localhost:5000/houses/a1b2c3d4-e5f6-7890-1234-567890abcdef
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "House retrieved successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "title": "Luxury Beachfront Villa",
    "description": "Stunning 4-bedroom villa with private pool and beach access. Perfect for families and groups. Fully equipped kitchen, modern amenities, and breathtaking ocean views.",
    "category": "Villa",
    "price_per_day": 250.00,
    "price_per_week": 1500.00,
    "price_per_month": 5000.00,
    "price_per_year": 50000.00,
    "currency": "USD",
    "address": "123 Ocean Drive",
    "city": "Miami",
    "country": "USA",
    "latitude": 25.7617,
    "longitude": -80.1918,
    "bedrooms": 4,
    "bathrooms": 3,
    "max_guests": 8,
    "square_feet": 3500,
    "floor_number": null,
    "features": [
      "WiFi",
      "Pool",
      "Air Conditioning",
      "Parking",
      "Kitchen",
      "Beach Access",
      "BBQ Grill",
      "Ocean View"
    ],
    "house_rules": "No smoking inside. No pets. Quiet hours after 10 PM. Maximum 8 guests.",
    "rating_average": 4.8,
    "review_count": 24,
    "is_available": true,
    "images": [
      {
        "id": "img1-uuid",
        "image_url": "/static/uploads/houses/a1b2c3d4_0_abc12345.jpg",
        "is_primary": true,
        "display_order": 0,
        "caption": "Front View"
      },
      {
        "id": "img2-uuid",
        "image_url": "/static/uploads/houses/a1b2c3d4_1_def67890.jpg",
        "is_primary": false,
        "display_order": 1,
        "caption": "Living Room"
      },
      {
        "id": "img3-uuid",
        "image_url": "/static/uploads/houses/a1b2c3d4_2_ghi13579.jpg",
        "is_primary": false,
        "display_order": 2,
        "caption": "Swimming Pool"
      }
    ],
    "owner": {
      "username": "johndoe",
      "profile_image": null
    }
  }
}
```

**Error Response (404 Not Found):**
```json
{
  "success": false,
  "message": "House not found",
  "data": null
}
```

---

### 3. Create House (Owner/Admin)

**Endpoint:** `POST /houses`  
**Auth:** Owner or Admin role required  
**Rate Limit:** 10 per hour  
**Content-Type:** application/json

**Required Fields:**
- title, description, price_per_day
- city, country, address
- bedrooms, bathrooms, max_guests

**Request:**
```bash
curl -X POST http://localhost:5000/houses \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Luxury Beachfront Villa",
    "description": "Stunning 4-bedroom villa with private pool...",
    "category": "Villa",
    "price_per_day": 250.00,
    "price_per_week": 1500.00,
    "price_per_month": 5000.00,
    "price_per_year": 50000.00,
    "currency": "USD",
    "address": "123 Ocean Drive",
    "city": "Miami",
    "country": "USA",
    "latitude": 25.7617,
    "longitude": -80.1918,
    "bedrooms": 4,
    "bathrooms": 3,
    "max_guests": 8,
    "square_feet": 3500,
    "features": ["WiFi", "Pool", "AC", "Parking", "Kitchen"],
    "house_rules": "No smoking. No pets.",
    "images": [
      {
        "image_url": "/static/uploads/houses/a1b2c3d4_0_abc12345.jpg",
        "is_primary": true,
        "display_order": 0,
        "caption": "Front View"
      },
      {
        "image_url": "/static/uploads/houses/a1b2c3d4_1_def67890.jpg",
        "display_order": 1,
        "caption": "Living Room"
      }
    ]
  }'
```

**Response (201 Created):**
```json
{
  "success": true,
  "message": "House created successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "title": "Luxury Beachfront Villa",
    "description": "Stunning 4-bedroom villa with private pool...",
    "owner_id": "owner-uuid-here",
    "status": "under_review",
    "is_verified": false,
    "created_at": "2024-12-14T10:30:00.123456",
    "updated_at": "2024-12-14T10:30:00.123456",
    /* ... all other fields ... */
  }
}
```

**Error Response (400 Bad Request):**
```json
{
  "success": false,
  "message": "Missing required field: bedrooms",
  "data": null
}
```

**Error Response (403 Forbidden):**
```json
{
  "success": false,
  "message": "Insufficient permissions. Required role(s): owner, admin",
  "data": null
}
```

---

### 4. Get My Houses (Authenticated)

**Endpoint:** `GET /houses/my-listings`  
**Auth:** JWT required  
**Rate Limit:** 50 per hour

**Request:**
```bash
curl http://localhost:5000/houses/my-listings \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Retrieved 3 houses",
  "data": [
    {
      "id": "house1-uuid",
      "title": "Luxury Villa",
      "owner_id": "your-user-uuid",
      "status": "active",
      "is_verified": true,
      "is_available": true,
      /* ... owner view includes all fields ... */
    },
    {
      "id": "house2-uuid",
      "title": "Beach House",
      "owner_id": "your-user-uuid",
      "status": "under_review",
      "is_verified": false,
      "is_available": true,
      /* ... */
    }
  ]
}
```

---

### 5. Update House (Owner Only)

**Endpoint:** `PUT /houses/<house_id>`  
**Auth:** JWT required (must be owner)  
**Rate Limit:** 50 per hour

**Request:**
```bash
curl -X PUT http://localhost:5000/houses/a1b2c3d4-e5f6-7890-1234-567890abcdef \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "price_per_day": 300.00,
    "price_per_week": 1800.00,
    "is_available": true,
    "house_rules": "Updated rules: No smoking anywhere on property."
  }'
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "House updated successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "price_per_day": 300.00,
    "price_per_week": 1800.00,
    "is_available": true,
    "updated_at": "2024-12-14T11:45:00.123456",
    /* ... all other fields ... */
  }
}
```

**Error Response (403 Forbidden):**
```json
{
  "success": false,
  "message": "Unauthorized: Not the owner",
  "data": null
}
```

---

### 6. Delete House (Owner Only)

**Endpoint:** `DELETE /houses/<house_id>`  
**Auth:** JWT required (must be owner)  
**Rate Limit:** 20 per hour

**Request:**
```bash
curl -X DELETE http://localhost:5000/houses/a1b2c3d4-e5f6-7890-1234-567890abcdef \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "House deleted successfully"
}
```

**Note:** This also deletes all associated images from storage.

---

### 7. Add Images to House (Owner Only)

**Endpoint:** `POST /houses/<house_id>/images`  
**Auth:** JWT required (must be owner)  
**Rate Limit:** 20 per hour

**Request:**
```bash
curl -X POST http://localhost:5000/houses/a1b2c3d4-e5f6-7890-1234-567890abcdef/images \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      {
        "image_url": "/static/uploads/houses/new_img_1.jpg",
        "is_primary": false,
        "display_order": 5,
        "caption": "Backyard"
      },
      {
        "image_url": "/static/uploads/houses/new_img_2.jpg",
        "display_order": 6,
        "caption": "Garage"
      }
    ]
  }'
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Added 2 images",
  "data": [
    {
      "id": "new-img1-uuid",
      "image_url": "/static/uploads/houses/new_img_1.jpg",
      "is_primary": false,
      "display_order": 5,
      "caption": "Backyard"
    },
    {
      "id": "new-img2-uuid",
      "image_url": "/static/uploads/houses/new_img_2.jpg",
      "is_primary": false,
      "display_order": 6,
      "caption": "Garage"
    }
  ]
}
```

---

### 8. Delete House Image (Owner Only)

**Endpoint:** `DELETE /houses/<house_id>/images/<image_id>`  
**Auth:** JWT required (must be owner)  
**Rate Limit:** 20 per hour

**Request:**
```bash
curl -X DELETE http://localhost:5000/houses/a1b2c3d4-uuid/images/img-uuid \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Image deleted successfully"
}
```

---

## 🚗 CAR ENDPOINTS

Car endpoints follow the same pattern as houses.

### 1. List All Cars (Public)

**Endpoint:** `GET /cars`  
**Auth:** None (Public)  
**Rate Limit:** 100 per hour

**Additional Query Parameters:**
- `make` - Filter by car make (Toyota, Honda, BMW, etc.)
- `min_year` / `max_year` - Year range
- `transmission` - manual or automatic
- `fuel_type` - petrol, diesel, electric, or hybrid
- `seats` - Minimum seats

**Example:**
```bash
curl "http://localhost:5000/cars?city=Los%20Angeles&make=Toyota&transmission=automatic&min_year=2020"
```

**Response (200 OK):**
```json
{
  "success": true,
  "data": {
    "cars": [
      {
        "id": "car1-uuid",
        "title": "2023 Toyota Camry - Premium Sedan",
        "make": "Toyota",
        "model": "Camry",
        "year": 2023,
        "category": "Sedan",
        "price_per_day": 50.00,
        "price_per_week": 300.00,
        "price_per_month": 1000.00,
        "currency": "USD",
        "city": "Los Angeles",
        "country": "USA",
        "seats": 5,
        "transmission": "automatic",
        "fuel_type": "petrol",
        "rating_average": 4.9,
        "review_count": 18,
        "is_available": true,
        "primary_image": "/static/uploads/cars/car1_0_abc123.jpg"
      }
    ],
    "total": 25,
    "page": 1,
    "per_page": 20,
    "pages": 2,
    "has_next": true,
    "has_prev": false
  }
}
```

---

### 2. Get Single Car (Public)

**Endpoint:** `GET /cars/<car_id>`  
**Auth:** None (Public)

**Request:**
```bash
curl http://localhost:5000/cars/car1-uuid
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Car retrieved successfully",
  "data": {
    "id": "car1-uuid",
    "title": "2023 Toyota Camry - Premium Sedan",
    "description": "Well-maintained luxury sedan with all modern features...",
    "make": "Toyota",
    "model": "Camry",
    "year": 2023,
    "category": "Sedan",
    "color": "Pearl White",
    "price_per_day": 50.00,
    "price_per_week": 300.00,
    "price_per_month": 1000.00,
    "price_per_year": 10000.00,
    "currency": "USD",
    "security_deposit": 500.00,
    "city": "Los Angeles",
    "country": "USA",
    "pickup_location": "LAX Airport, Terminal 1",
    "latitude": 33.9416,
    "longitude": -118.4085,
    "seats": 5,
    "transmission": "automatic",
    "fuel_type": "petrol",
    "mileage": 15000,
    "engine_capacity": "2.5L",
    "features": [
      "GPS Navigation",
      "Bluetooth",
      "Backup Camera",
      "Cruise Control",
      "Sunroof",
      "Heated Seats"
    ],
    "insurance_included": true,
    "fuel_policy": "Full-to-Full",
    "minimum_age": 25,
    "driving_license_required": true,
    "rental_terms": "Valid driver's license required. International licenses accepted with passport.",
    "rating_average": 4.9,
    "review_count": 18,
    "is_available": true,
    "images": [
      {
        "id": "img1-uuid",
        "image_url": "/static/uploads/cars/car1_0_abc123.jpg",
        "is_primary": true,
        "display_order": 0,
        "caption": "Front View"
      },
      {
        "id": "img2-uuid",
        "image_url": "/static/uploads/cars/car1_1_def456.jpg",
        "is_primary": false,
        "display_order": 1,
        "caption": "Interior Dashboard"
      }
    ],
    "owner": {
      "username": "carowner",
      "profile_image": null
    }
  }
}
```

**Note:** License plate is NOT included in public view for privacy.

---

### 3. Create Car (Owner/Admin)

**Endpoint:** `POST /cars`  
**Auth:** Owner or Admin role required  
**Rate Limit:** 10 per hour

**Required Fields:**
- title, description, make, model, year
- license_plate, seats, transmission, fuel_type
- price_per_day, city, country

**Request:**
```bash
curl -X POST http://localhost:5000/cars \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "2023 Toyota Camry - Premium Sedan",
    "description": "Well-maintained luxury sedan...",
    "make": "Toyota",
    "model": "Camry",
    "year": 2023,
    "category": "Sedan",
    "color": "Pearl White",
    "license_plate": "ABC123",
    "seats": 5,
    "transmission": "automatic",
    "fuel_type": "petrol",
    "mileage": 15000,
    "engine_capacity": "2.5L",
    "price_per_day": 50.00,
    "price_per_week": 300.00,
    "price_per_month": 1000.00,
    "currency": "USD",
    "security_deposit": 500.00,
    "city": "Los Angeles",
    "country": "USA",
    "pickup_location": "LAX Airport",
    "latitude": 33.9416,
    "longitude": -118.4085,
    "features": ["GPS", "Bluetooth", "Backup Camera"],
    "insurance_included": true,
    "fuel_policy": "Full-to-Full",
    "minimum_age": 25,
    "rental_terms": "Valid license required",
    "images": [
      {
        "image_url": "/static/uploads/cars/car1_0_abc123.jpg",
        "is_primary": true,
        "display_order": 0
      }
    ]
  }'
```

**Response (201 Created):**
```json
{
  "success": true,
  "message": "Car created successfully",
  "data": {
    "id": "car1-uuid",
    "owner_id": "your-uuid",
    "status": "under_review",
    "is_verified": false,
    "license_plate": "ABC123",
    /* ... all fields including owner view ... */
  }
}
```

**Error (Invalid Enum):**
```json
{
  "success": false,
  "message": "Invalid transmission or fuel_type. Use: manual/automatic, petrol/diesel/electric/hybrid",
  "data": null
}
```

---

### 4. Get My Cars

**Endpoint:** `GET /cars/my-listings`  
**Same as houses**

```bash
curl http://localhost:5000/cars/my-listings \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
```

---

### 5. Update Car

**Endpoint:** `PUT /cars/<car_id>`  
**Same pattern as houses**

**Note:** Cannot update: make, model, year, license_plate (immutable)

---

### 6. Delete Car

**Endpoint:** `DELETE /cars/<car_id>`  
**Same pattern as houses**

---

### 7 & 8. Car Image Management

**Add Images:** `POST /cars/<car_id>/images`  
**Delete Image:** `DELETE /cars/<car_id>/images/<image_id>`

**Same pattern as houses**

---

## 📸 Image Serving

### Access Uploaded Images

Images are accessible via static URLs:

```bash
# House image
http://localhost:5000/static/uploads/houses/a1b2c3d4_0_abc12345.jpg

# Car image
http://localhost:5000/static/uploads/cars/b2c3d4e5_0_def67890.jpg
```

**In HTML/React:**
```html
<img src="http://localhost:5000/static/uploads/houses/a1b2c3d4_0_abc12345.jpg" alt="Villa" />
```

**Optional Protected Endpoint:**

If you register the images blueprint:
```bash
# Public access
http://localhost:5000/images/houses/filename.jpg
http://localhost:5000/images/cars/filename.jpg

# Protected access (requires JWT)
http://localhost:5000/images/private/houses/filename.jpg
http://localhost:5000/images/private/cars/filename.jpg
```

---

## 🔄 Complete Workflow Examples

### Create a House Listing (Complete Flow)

```bash
# Step 1: Login as owner
curl -X POST http://localhost:5000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email_or_username": "owner@example.com",
    "password": "password123"
  }'

# Save the access_token from response

# Step 2: Upload images
curl -X POST http://localhost:5000/uploads/house-images \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "images=@villa-front.jpg" \
  -F "images=@villa-pool.jpg" \
  -F "images=@villa-bedroom.jpg"

# Save the image URLs from response

# Step 3: Create house
curl -X POST http://localhost:5000/houses \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Luxury Beach Villa",
    "description": "Amazing villa...",
    "price_per_day": 250.00,
    "city": "Miami",
    "country": "USA",
    "address": "123 Ocean Dr",
    "bedrooms": 4,
    "bathrooms": 3,
    "max_guests": 8,
    "features": ["Pool", "WiFi"],
    "images": [
      {"image_url": "/static/uploads/houses/...", "is_primary": true, "display_order": 0},
      {"image_url": "/static/uploads/houses/...", "display_order": 1},
      {"image_url": "/static/uploads/houses/...", "display_order": 2}
    ]
  }'

# Step 4: View your listing
curl http://localhost:5000/houses/YOUR_HOUSE_ID

# Step 5: Update pricing
curl -X PUT http://localhost:5000/houses/YOUR_HOUSE_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price_per_day": 300.00}'
```

---

### Search for Cars

```bash
# Find automatic cars in LA, 2020 or newer, under $100/day
curl "http://localhost:5000/cars?city=Los%20Angeles&transmission=automatic&min_year=2020&max_price=100"

# Find electric SUVs
curl "http://localhost:5000/cars?category=SUV&fuel_type=electric"

# Paginate results
curl "http://localhost:5000/cars?city=Miami&page=2&per_page=10"
```

---

## 📊 Rate Limits Summary

| Endpoint | Limit |
|----------|-------|
| GET /houses, /cars | 100/hour |
| GET /houses/<id>, /cars/<id> | 100/hour |
| POST /houses, /cars | 10/hour |
| GET /my-listings | 50/hour |
| PUT /houses, /cars | 50/hour |
| DELETE | 20/hour |
| POST /uploads/* | 20/hour |
| Image management | 20/hour |

---

## ✅ HTTP Status Codes

| Code | Meaning | When |
|------|---------|------|
| 200 | OK | Successful GET, PUT, DELETE |
| 201 | Created | Successful POST (create) |
| 400 | Bad Request | Invalid data, missing fields |
| 401 | Unauthorized | No token or invalid token |
| 403 | Forbidden | Wrong role or not owner |
| 404 | Not Found | Resource doesn't exist |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Server Error | Internal error |

---

## 🎯 Quick Reference

**Public Endpoints (No Auth):**
```bash
GET  /houses
GET  /houses/<id>
GET  /cars
GET  /cars/<id>
```

**Owner/Admin Only:**
```bash
POST /houses
POST /cars
POST /uploads/house-images
POST /uploads/car-images
```

**Owner Only (Must Own Property):**
```bash
PUT    /houses/<id>
DELETE /houses/<id>
PUT    /cars/<id>
DELETE /cars/<id>
POST   /houses/<id>/images
DELETE /houses/<id>/images/<img_id>
POST   /cars/<id>/images
DELETE /cars/<id>/images/<img_id>
```

**Authenticated Users:**
```bash
GET /houses/my-listings
GET /cars/my-listings
```

---

## 🚀 Ready to Use!

Your complete properties API is ready with:
- ✅ 20 endpoints
- ✅ Full CRUD operations
- ✅ Image upload & serving
- ✅ Role-based access control
- ✅ Filtering & pagination
- ✅ Complete documentation

**Start testing with these curl examples!** 💪