rentcache/docs/API.md

# API Reference

Complete reference documentation for all RentCache API endpoints, including Rentcast proxy endpoints and system management endpoints.

## 📋 Overview

RentCache provides two types of endpoints:

1. **Proxy Endpoints** (`/api/v1/*`) - Mirror Rentcast API endpoints with intelligent caching
2. **System Endpoints** - Health checks, metrics, and administration

All endpoints support JSON responses and include cache performance headers.

## 🔐 Authentication

All API endpoints require Bearer token authentication using your Rentcast API key:

```http
Authorization: Bearer YOUR_RENTCAST_API_KEY
```

**Example**:
```bash
curl -H "Authorization: Bearer sk_live_1234567890abcdef" \
  "http://localhost:8000/api/v1/properties?city=Austin&state=TX"
```

## 📊 Common Response Headers

All responses include performance and cache information:

| Header | Description | Example |
|--------|-------------|---------|
| `X-Cache-Hit` | Whether response was served from cache | `true` or `false` |
| `X-Response-Time-MS` | Total response time in milliseconds | `45.2` |
| `X-Estimated-Cost` | Estimated Rentcast API cost (cache misses only) | `2.0` |

## 🏠 Property Endpoints

### Search Properties

Search for property records using various criteria.

**Endpoint**: `GET /api/v1/properties`  
**Cache TTL**: 24 hours  
**Estimated Cost**: $1.00 per request  
**Rate Limit**: 60/minute

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `address` | string | No | Full or partial address |
| `zipCode` | string | No | ZIP/postal code |
| `city` | string | No | City name |
| `state` | string | No | State abbreviation (e.g., "TX") |
| `propertyType` | string | No | Property type filter |
| `bedrooms` | integer | No | Number of bedrooms |
| `bathrooms` | number | No | Number of bathrooms (supports decimals) |
| `squareFootage` | integer | No | Square footage |
| `offset` | integer | No | Pagination offset (default: 0) |
| `limit` | integer | No | Results per page (default: 100, max: 500) |
| `force_refresh` | boolean | No | Force cache refresh (default: false) |
| `ttl_override` | integer | No | Override cache TTL in seconds |

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/properties?city=Austin&state=TX&propertyType=Single%20Family&bedrooms=3&limit=10"
```

#### Example Response

```json
{
  "status": "success",
  "data": [
    {
      "id": "12345",
      "address": "123 Main St",
      "city": "Austin", 
      "state": "TX",
      "zipCode": "78701",
      "propertyType": "Single Family",
      "bedrooms": 3,
      "bathrooms": 2,
      "squareFootage": 1800,
      "lotSize": 0.25,
      "yearBuilt": 1995,
      "lastSalePrice": 450000,
      "lastSaleDate": "2023-06-15",
      "estimatedValue": 485000,
      "latitude": 30.2672,
      "longitude": -97.7431
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 1,
    "hasMore": false
  }
}
```

### Get Property by ID

Retrieve detailed information for a specific property.

**Endpoint**: `GET /api/v1/properties/{property_id}`  
**Cache TTL**: 24 hours  
**Estimated Cost**: $1.00 per request  
**Rate Limit**: 60/minute

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `property_id` | string | Yes | Unique property identifier |
| `force_refresh` | boolean | No | Force cache refresh |
| `ttl_override` | integer | No | Override cache TTL in seconds |

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/properties/12345"
```

#### Example Response

```json
{
  "status": "success",
  "data": {
    "id": "12345",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zipCode": "78701",
    "propertyType": "Single Family",
    "bedrooms": 3,
    "bathrooms": 2,
    "squareFootage": 1800,
    "lotSize": 0.25,
    "yearBuilt": 1995,
    "assessedValue": 475000,
    "marketValue": 485000,
    "propertyHistory": [
      {
        "date": "2023-06-15",
        "price": 450000,
        "type": "sale"
      }
    ],
    "neighborhood": {
      "name": "Downtown Austin",
      "walkScore": 85,
      "crimeScore": "Low"
    }
  }
}
```

## 💰 Value Estimation Endpoints

### Get Property Value Estimate

Get an estimated market value for a property.

**Endpoint**: `GET /api/v1/estimates/value`  
**Cache TTL**: 1 hour  
**Estimated Cost**: $2.00 per request  
**Rate Limit**: 30/minute

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `address` | string | No | Property address |
| `zipCode` | string | No | ZIP code |
| `city` | string | No | City name |
| `state` | string | No | State abbreviation |
| `propertyType` | string | No | Property type |
| `bedrooms` | integer | No | Number of bedrooms |
| `bathrooms` | number | No | Number of bathrooms |
| `squareFootage` | integer | No | Square footage |
| `force_refresh` | boolean | No | Force cache refresh |
| `ttl_override` | integer | No | Override cache TTL |

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/estimates/value?address=123%20Main%20St&city=Austin&state=TX"
```

#### Example Response

```json
{
  "status": "success",
  "data": {
    "address": "123 Main St, Austin, TX 78701",
    "estimatedValue": 485000,
    "confidence": 85,
    "valuationRange": {
      "low": 460000,
      "high": 510000
    },
    "comparables": [
      {
        "address": "125 Main St",
        "salePrice": 475000,
        "saleDate": "2023-08-12",
        "distance": 0.1
      }
    ],
    "marketTrends": {
      "monthlyChange": 2.1,
      "yearlyChange": 8.5
    },
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}
```

### Bulk Value Estimates

Get value estimates for multiple properties in a single request.

**Endpoint**: `POST /api/v1/estimates/value/bulk`  
**Cache TTL**: 1 hour  
**Estimated Cost**: $10.00 per request  
**Rate Limit**: 10/minute

#### Request Body

```json
{
  "properties": [
    {
      "address": "123 Main St",
      "city": "Austin",
      "state": "TX"
    },
    {
      "address": "456 Oak Ave", 
      "city": "Austin",
      "state": "TX"
    }
  ],
  "force_refresh": false,
  "ttl_override": 7200
}
```

#### Example Request

```bash
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": [
      {"address": "123 Main St", "city": "Austin", "state": "TX"},
      {"address": "456 Oak Ave", "city": "Austin", "state": "TX"}
    ]
  }' \
  "http://localhost:8000/api/v1/estimates/value/bulk"
```

## 🏠 Rent Estimation Endpoints

### Get Rent Estimate

Get an estimated rental value for a property.

**Endpoint**: `GET /api/v1/estimates/rent`  
**Cache TTL**: 1 hour  
**Estimated Cost**: $2.00 per request  
**Rate Limit**: 30/minute

#### Parameters

Same as value estimation endpoint.

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/estimates/rent?address=123%20Main%20St&city=Austin&state=TX"
```

#### Example Response

```json
{
  "status": "success",
  "data": {
    "address": "123 Main St, Austin, TX 78701",
    "estimatedRent": 2450,
    "confidence": 82,
    "rentRange": {
      "low": 2200,
      "high": 2700
    },
    "comparables": [
      {
        "address": "125 Main St",
        "rent": 2400,
        "bedrooms": 3,
        "bathrooms": 2,
        "distance": 0.1
      }
    ],
    "marketMetrics": {
      "averageRent": 2380,
      "rentPerSqFt": 1.36,
      "occupancyRate": 94.2
    },
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}
```

### Bulk Rent Estimates

Get rent estimates for multiple properties.

**Endpoint**: `POST /api/v1/estimates/rent/bulk`  
**Cache TTL**: 1 hour  
**Estimated Cost**: $10.00 per request  
**Rate Limit**: 10/minute

Similar to bulk value estimates but returns rental estimates.

## 🏘️ Listings Endpoints

### Search Sale Listings

Search for properties currently for sale.

**Endpoint**: `GET /api/v1/listings/sale`  
**Cache TTL**: 30 minutes  
**Estimated Cost**: $0.50 per request  
**Rate Limit**: 60/minute

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `address` | string | No | Address filter |
| `zipCode` | string | No | ZIP code filter |
| `city` | string | No | City filter |
| `state` | string | No | State filter |
| `propertyType` | string | No | Property type filter |
| `bedrooms` | integer | No | Bedroom count filter |
| `bathrooms` | number | No | Bathroom count filter |
| `minPrice` | integer | No | Minimum listing price |
| `maxPrice` | integer | No | Maximum listing price |
| `offset` | integer | No | Pagination offset |
| `limit` | integer | No | Results per page |

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/listings/sale?city=Austin&state=TX&bedrooms=3&minPrice=300000&maxPrice=600000"
```

#### Example Response

```json
{
  "status": "success",
  "data": [
    {
      "id": "listing_123",
      "address": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zipCode": "78701",
      "price": 485000,
      "bedrooms": 3,
      "bathrooms": 2,
      "squareFootage": 1800,
      "lotSize": 0.25,
      "propertyType": "Single Family",
      "listingDate": "2024-01-10",
      "daysOnMarket": 5,
      "status": "Active",
      "mls": "12345678",
      "photos": [
        "https://example.com/photo1.jpg"
      ],
      "description": "Beautiful home in downtown Austin..."
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 1,
    "hasMore": false
  }
}
```

### Search Rental Listings

Search for rental properties.

**Endpoint**: `GET /api/v1/listings/rental`  
**Cache TTL**: 30 minutes  
**Estimated Cost**: $0.50 per request  
**Rate Limit**: 60/minute

#### Parameters

Similar to sale listings, but with `minRent`/`maxRent` instead of price filters.

#### Example Response

```json
{
  "status": "success", 
  "data": [
    {
      "id": "rental_456",
      "address": "456 Oak Ave",
      "city": "Austin",
      "state": "TX",
      "rent": 2400,
      "bedrooms": 2,
      "bathrooms": 2,
      "squareFootage": 1200,
      "propertyType": "Apartment",
      "availableDate": "2024-02-01",
      "leaseTerms": "12 months",
      "petPolicy": "Cats allowed",
      "amenities": ["Pool", "Gym", "Parking"],
      "photos": ["https://example.com/rental1.jpg"]
    }
  ]
}
```

### Get Listing by ID

Get detailed information for a specific listing.

**Endpoint**: `GET /api/v1/listings/{listing_id}`  
**Cache TTL**: 1 hour  
**Estimated Cost**: $0.50 per request  
**Rate Limit**: 60/minute

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/listings/listing_123"
```

## 📈 Market Data Endpoints

### Market Statistics

Get comprehensive market statistics for an area.

**Endpoint**: `GET /api/v1/markets/stats`  
**Cache TTL**: 2 hours  
**Estimated Cost**: $5.00 per request  
**Rate Limit**: 20/minute

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `zipCode` | string | No | ZIP code for market area |
| `city` | string | No | City name |
| `state` | string | No | State abbreviation |
| `force_refresh` | boolean | No | Force cache refresh |
| `ttl_override` | integer | No | Override cache TTL |

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/markets/stats?zipCode=78701"
```

#### Example Response

```json
{
  "status": "success",
  "data": {
    "location": {
      "zipCode": "78701",
      "city": "Austin",
      "state": "TX"
    },
    "salesMetrics": {
      "medianSalePrice": 485000,
      "averageSalePrice": 512000,
      "totalSales": 156,
      "daysOnMarket": 28,
      "pricePerSqFt": 275,
      "monthlyChange": 2.1,
      "yearlyChange": 8.5
    },
    "rentalMetrics": {
      "medianRent": 2400,
      "averageRent": 2450,
      "totalRentals": 89,
      "vacancyRate": 5.8,
      "rentPerSqFt": 1.36,
      "monthlyChange": 1.2,
      "yearlyChange": 12.3
    },
    "marketTrends": {
      "inventoryLevel": "Low",
      "marketTempo": "Fast",
      "buyerDemand": "High",
      "priceDirection": "Rising"
    },
    "demographics": {
      "medianHouseholdIncome": 65000,
      "population": 15420,
      "medianAge": 32
    },
    "lastUpdated": "2024-01-15T10:30:00Z"
  }
}
```

### Comparable Properties

Find comparable properties for analysis.

**Endpoint**: `GET /api/v1/comparables`  
**Cache TTL**: 1 hour  
**Estimated Cost**: $3.00 per request  
**Rate Limit**: 30/minute

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `address` | string | No | Subject property address |
| `zipCode` | string | No | ZIP code |
| `city` | string | No | City name |
| `state` | string | No | State abbreviation |
| `propertyType` | string | No | Property type |
| `bedrooms` | integer | No | Number of bedrooms |
| `bathrooms` | number | No | Number of bathrooms |
| `squareFootage` | integer | No | Square footage |
| `radius` | number | No | Search radius in miles (default: 1.0) |
| `maxComps` | integer | No | Maximum comparables to return (default: 10) |

#### Example Request

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://localhost:8000/api/v1/comparables?address=123%20Main%20St&city=Austin&state=TX&radius=0.5"
```

#### Example Response

```json
{
  "status": "success",
  "data": {
    "subjectProperty": {
      "address": "123 Main St",
      "city": "Austin",
      "state": "TX"
    },
    "comparables": [
      {
        "address": "125 Main St",
        "salePrice": 475000,
        "saleDate": "2023-08-12",
        "bedrooms": 3,
        "bathrooms": 2,
        "squareFootage": 1750,
        "lotSize": 0.22,
        "yearBuilt": 1992,
        "distance": 0.1,
        "similarity": 95,
        "adjustments": {
          "location": 0,
          "size": 5000,
          "age": -2000,
          "condition": 0
        },
        "adjustedPrice": 478000
      }
    ],
    "summary": {
      "averagePrice": 478000,
      "priceRange": {
        "low": 460000,
        "high": 495000
      },
      "averagePricePerSqFt": 268,
      "confidenceScore": 88
    }
  }
}
```

## 🛠️ System Endpoints

### Health Check

Check system health and status.

**Endpoint**: `GET /health`  
**Authentication**: None required  
**Rate Limit**: None

#### Example Request

```bash
curl http://localhost:8000/health
```

#### Example Response

```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "database": "healthy",
  "cache_backend": "sqlite",
  "active_keys": 3,
  "total_cache_entries": 1234,
  "cache_hit_ratio_24h": 0.89
}
```

### System Metrics

Get detailed system performance metrics.

**Endpoint**: `GET /metrics`  
**Authentication**: None required  
**Rate Limit**: 10/minute

#### Example Request

```bash
curl http://localhost:8000/metrics
```

#### Example Response

```json
{
  "total_requests": 2543,
  "cache_hits": 2287,
  "cache_misses": 256,
  "cache_hit_ratio": 0.8992,
  "active_api_keys": 3,
  "total_cost_saved": 4574.0,
  "avg_response_time_ms": 28.5,
  "uptime_seconds": 86400,
  "requests_24h": 456,
  "cache_hits_24h": 405,
  "cost_24h": 102.0,
  "top_endpoints": [
    {
      "endpoint": "properties",
      "requests": 1205
    },
    {
      "endpoint": "value_estimate", 
      "requests": 892
    },
    {
      "endpoint": "listings_sale",
      "requests": 234
    }
  ]
}
```

## 🔧 Administration Endpoints

### Create API Key

Create a new API key for application access.

**Endpoint**: `POST /admin/api-keys`  
**Authentication**: Admin required (implementation-specific)  
**Rate Limit**: 5/minute

#### Request Body

```json
{
  "key_name": "production_app",
  "rentcast_api_key": "sk_live_1234567890abcdef",
  "daily_limit": 5000,
  "monthly_limit": 100000,
  "expires_at": "2024-12-31T23:59:59Z"
}
```

#### Example Request

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "my_app",
    "rentcast_api_key": "sk_live_1234567890abcdef",
    "daily_limit": 1000,
    "monthly_limit": 10000
  }' \
  "http://localhost:8000/admin/api-keys"
```

#### Example Response

```json
{
  "id": 1,
  "key_name": "my_app",
  "daily_limit": 1000,
  "monthly_limit": 10000,
  "daily_usage": 0,
  "monthly_usage": 0,
  "is_active": true,
  "expires_at": null,
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Clear Cache

Clear cache entries based on criteria.

**Endpoint**: `POST /admin/cache/clear`  
**Authentication**: Admin required  
**Rate Limit**: 5/minute

#### Request Body

```json
{
  "endpoint": "properties",
  "older_than_hours": 24,
  "invalid_only": false
}
```

#### Example Request

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "properties",
    "older_than_hours": 24
  }' \
  "http://localhost:8000/admin/cache/clear"
```

#### Example Response

```json
{
  "message": "Cleared 156 cache entries",
  "pattern": "*properties*"
}
```

## 🚫 Error Responses

All endpoints return consistent error responses:

### HTTP Status Codes

| Code | Meaning | Description |
|------|---------|-------------|
| 200 | OK | Request successful |
| 400 | Bad Request | Invalid parameters |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | API key lacks permissions |
| 404 | Not Found | Resource not found |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server error |
| 502 | Bad Gateway | Upstream API error |
| 503 | Service Unavailable | Service temporarily unavailable |

### Error Response Format

```json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily API limit of 1000 requests exceeded",
    "details": {
      "daily_usage": 1001,
      "daily_limit": 1000,
      "reset_time": "2024-01-16T00:00:00Z"
    }
  }
}
```

### Common Error Codes

| Code | Description |
|------|-------------|
| `INVALID_API_KEY` | API key not found or inactive |
| `RATE_LIMIT_EXCEEDED` | Request rate limit exceeded |
| `INVALID_PARAMETERS` | Request parameters validation failed |
| `UPSTREAM_API_ERROR` | Error from Rentcast API |
| `CACHE_ERROR` | Cache system error |
| `DATABASE_ERROR` | Database connection error |

## 📊 Response Caching

### Cache Headers

All responses include cache-related headers:

```http
X-Cache-Hit: true
X-Response-Time-MS: 12.5
X-Cache-Age: 3600
X-Cache-TTL: 86400
```

### Cache Key Generation

Cache keys are generated using MD5 hash of:
- HTTP method
- Endpoint name  
- Sorted query parameters
- Request body (for POST requests)

Example: `GET:properties:{"city":"Austin","state":"TX"}` → `a1b2c3d4e5f6...`

### Cache Invalidation

Cache entries can be invalidated:
- Automatically when TTL expires
- Manually via admin endpoints
- Using `force_refresh=true` parameter
- Through CLI commands

## 🔄 Rate Limiting

### Rate Limit Headers

Rate-limited endpoints include headers:

```http
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642248000
X-RateLimit-Window: 60
```

### Rate Limit Tiers

| Endpoint Type | Rate Limit | Burst Allowance |
|---------------|------------|-----------------|
| Property Search | 60/minute | 10 requests |
| Value Estimates | 30/minute | 5 requests |
| Market Stats | 20/minute | 3 requests |
| Listings | 60/minute | 10 requests |
| Bulk Operations | 10/minute | 2 requests |

### Rate Limit Bypass

Cache hits do not count against rate limits, providing natural rate limit relief through caching.

---

## 📚 Additional Resources

- **[Installation Guide](INSTALLATION.md)** - Setup and configuration
- **[Usage Guide](USAGE.md)** - Comprehensive usage examples
- **[Rentcast API Documentation](https://developers.rentcast.io/reference/introduction)** - Official API docs

For questions or issues, please refer to the project repository at [git.supported.systems/MCP/rentcache](https://git.supported.systems/MCP/rentcache).