API
Endpoints
Complete reference for 18 endpoints across valuations, scores, projections, signals, and portfolio management with full request/response examples.
Introduction
The Prophetic API exposes luxury intelligence through a comprehensive set of RESTful endpoints. This reference documents every available endpoint, including request parameters, response formats, and practical examples.
Every response includes Market Scout validation status and reflects our 91% algorithmic accuracy across all 10 segments.
Note: All endpoints require authentication via Bearer token. See Getting Started for authentication details.
Endpoints Overview
API Structure
json
{ "api": { "base_url": "https://api.prophetic.ai/v1", "format": "JSON", "authentication": "Bearer token", "versioning": "URL path", "accuracy": "91%", "assets": "32,000+" } } ``` ### Endpoint Categories ``` ENDPOINT CATEGORIES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Category Endpoints Purpose ────────────────────────────────────────────────── Authentication 2 Token management Valuations 3 Asset pricing (91% accuracy) Scores 2 Investment ratings (0-100) Projections 2 3-scenario ROI forecasting Signals 3 Market intelligence Portfolio 4 Holdings management Segments 2 Category data Exit 2 Disposition intelligence ────────────────────────────────────────────────── TOTAL 20 Full luxury intelligence ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` > **Tip:** Each category serves a specific intelligence function. --- ## Authentication ### POST /auth/token Get an access token using client credentials. ``` POST https://api.prophetic.ai/v1/auth/token
Request Body
json
{ "client_id": "your_client_id", "client_secret": "your_client_secret", "grant_type": "client_credentials" }
Response
json
{ "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "Bearer", "expires_in": 3600, "scope": "valuations scores projections signals portfolio exit" } ``` | Field | Type | Description | |-------|------|-------------| | `access_token` | string | JWT token for API requests | | `token_type` | string | Always "Bearer" | | `expires_in` | integer | Token validity in seconds | | `scope` | string | Authorised endpoint access | ### POST /auth/refresh Refresh an expired access token. ``` POST https://api.prophetic.ai/v1/auth/refresh
Request Body
json
{ "refresh_token": "your_refresh_token", "grant_type": "refresh_token" }
Response
json
{ "access_token": "eyJhbGciOiJSUzI1NiIs...", "refresh_token": "new_refresh_token", "token_type": "Bearer", "expires_in": 3600 } ``` > **Tip:** Implement automatic token refresh before expiry for uninterrupted access. --- ## Valuations ### Valuation Endpoints ``` VALUATION ENDPOINTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Endpoint Method Purpose ────────────────────────────────────────────────── /valuations POST Get asset valuation /valuations/{id} GET Retrieve by ID /valuations/batch POST Multiple assets (max 50) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### POST /valuations Get real-time valuation for a luxury asset with 91% accuracy. ``` POST https://api.prophetic.ai/v1/valuations
Request Body
json
{ "segment": "watches", "brand": "Rolex", "model": "Daytona", "reference": "126500LN", "year": 2023, "condition": "excellent", "box_papers": true }
Parameters
Parameter | Type | Required | Description |
|---|---|---|---|
| string | Yes | One of 10 luxury segments |
| string | Yes | Brand name |
| string | Yes | Model name |
| string | No | Reference number |
| integer | No | Production year |
| string | No | excellent/very_good/good/fair |
| boolean | No | Original packaging |
Response
json
{ "valuation": { "id": "val_8f7d6c5b4a3e2f1d", "asset_id": "PRO-WAT-RLX-126500LN-2023", "segment": "watches", "brand": "Rolex", "model": "Daytona", "reference": "126500LN", "estimated_value": { "low": 24500, "mid": 26200, "high": 27800, "currency": "EUR" }, "confidence": 0.91, "data_points": 847, "prophetic_score": 82, "momentum": "positive", "vs_segment_avg": "+12%", "market_scout_validated": true, "generated_at": "2025-01-28T10:30:00Z", "valid_until": "2025-01-29T10:30:00Z" } } ``` ### GET /valuations/{id} Retrieve a previously generated valuation. ``` GET https://api.prophetic.ai/v1/valuations/val_8f7d6c5b4a3e2f1d
Response
json
{ "valuation": { "id": "val_8f7d6c5b4a3e2f1d", "asset_id": "PRO-WAT-RLX-126500LN-2023", "estimated_value": { "low": 24500, "mid": 26200, "high": 27800, "currency": "EUR" }, "prophetic_score": 82, "status": "valid", "market_scout_validated": true, "generated_at": "2025-01-28T10:30:00Z" } } ``` ### POST /valuations/batch Get valuations for multiple assets in one request. ``` POST https://api.prophetic.ai/v1/valuations/batch
Request Body
json
{ "assets": [ { "segment": "watches", "brand": "Rolex", "model": "Daytona", "reference": "126500LN" }, { "segment": "watches", "brand": "Patek Philippe", "model": "Nautilus", "reference": "5711/1A" }, { "segment": "bags", "brand": "Hermès", "model": "Birkin", "size": "30" } ] }
Response
json
{ "batch_id": "batch_1a2b3c4d5e6f", "count": 3, "valuations": [ { "asset_id": "PRO-WAT-RLX-126500LN", "estimated_value": { "mid": 26200, "currency": "EUR" }, "prophetic_score": 82, "confidence": 0.91 }, { "asset_id": "PRO-WAT-PP-5711-1A", "estimated_value": { "mid": 142000, "currency": "EUR" }, "prophetic_score": 89, "confidence": 0.89 }, { "asset_id": "PRO-BAG-HER-BIRKIN-30", "estimated_value": { "mid": 12500, "currency": "EUR" }, "prophetic_score": 76, "confidence": 0.87 } ], "total_value": 180700, "market_scout_validated": true, "generated_at": "2025-01-28T10:30:00Z" } ``` > **Note:** Batch requests are limited to 50 assets per call. --- ## Scores ### Score Endpoints ``` SCORE ENDPOINTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Endpoint Method Purpose ────────────────────────────────────────────────── /scores POST Get Prophetic Score (0-100) /scores/breakdown POST Detailed 6-factor breakdown ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### POST /scores Get the Prophetic Score for an asset. ``` POST https://api.prophetic.ai/v1/scores
Request Body
json
{ "segment": "art", "artist": "Jean-Michel Basquiat", "title": "Untitled", "year": 1982, "medium": "acrylic on canvas", "size_cm": { "width": 183, "height": 173 } }
Response
json
{ "score": { "asset_id": "PRO-ART-BAS-1982-UNT", "prophetic_score": 94, "classification": "exceptional", "momentum": "positive", "confidence": 0.88, "percentile": 97, "vs_segment_avg": "+18%", "market_scout_validated": true, "generated_at": "2025-01-28T10:30:00Z" } } ``` ### POST /scores/breakdown Get detailed score breakdown by the 6 evaluation factors. ``` POST https://api.prophetic.ai/v1/scores/breakdown
Request Body
json
{ "asset_id": "PRO-ART-BAS-1982-UNT" }
Response
json
{ "breakdown": { "asset_id": "PRO-ART-BAS-1982-UNT", "prophetic_score": 94, "factors": { "rarity_edition": { "score": 95, "weight": 0.20, "contribution": 19.0 }, "market_desirability": { "score": 96, "weight": 0.20, "contribution": 19.2 }, "historical_valorisation": { "score": 92, "weight": 0.15, "contribution": 13.8 }, "liquidity_profile": { "score": 88, "weight": 0.15, "contribution": 13.2 }, "institutional_recognition": { "score": 98, "weight": 0.15, "contribution": 14.7 }, "appreciation_potential": { "score": 91, "weight": 0.15, "contribution": 13.65 } }, "weighted_total": 94, "market_scout_validated": true, "generated_at": "2025-01-28T10:30:00Z" } } ``` > **Note:** Score breakdown reveals contribution of each of the 6 evaluation criteria. --- ## Projections ### Projection Endpoints ``` PROJECTION ENDPOINTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Endpoint Method Purpose ────────────────────────────────────────────────── /projections POST 3-scenario ROI projections /projections/{id} GET Retrieve projection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### POST /projections Get ROI projections across 3 scenarios and multiple horizons. ``` POST https://api.prophetic.ai/v1/projections
Request Body
json
{ "asset_id": "PRO-WAT-RLX-126500LN-2023", "current_value": 26200, "horizons": [12, 24, 36], "scenarios": ["conservative", "central", "optimistic"] }
Response
json
{ "projection": { "id": "proj_9e8d7c6b5a4f3e2d", "asset_id": "PRO-WAT-RLX-126500LN-2023", "current_value": 26200, "currency": "EUR", "scenarios": { "conservative": { "probability": 0.30, "12_months": { "value": 27200, "roi_percent": 3.8 }, "24_months": { "value": 28400, "roi_percent": 8.4 }, "36_months": { "value": 29800, "roi_percent": 13.7 } }, "central": { "probability": 0.50, "12_months": { "value": 28500, "roi_percent": 8.8 }, "24_months": { "value": 31200, "roi_percent": 19.1 }, "36_months": { "value": 34100, "roi_percent": 30.2 } }, "optimistic": { "probability": 0.20, "12_months": { "value": 30200, "roi_percent": 15.3 }, "24_months": { "value": 35800, "roi_percent": 36.6 }, "36_months": { "value": 42500, "roi_percent": 62.2 } } }, "expected_roi": { "12_months": 9.2, "24_months": 20.8, "36_months": 34.0 }, "confidence": 0.91, "market_scout_validated": true, "generated_at": "2025-01-28T10:30:00Z" } } ``` > **Tip:** Expected ROI is probability-weighted across all 3 scenarios. --- ## Signals ### Signal Endpoints ``` SIGNAL ENDPOINTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Endpoint Method Purpose ────────────────────────────────────────────────── /signals GET All market signals /signals/{segment} GET Segment signals /signals/alerts GET Active alerts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### GET /signals Get current market signals across all 10 segments. ``` GET https://api.prophetic.ai/v1/signals
Response
json
{ "signals": { "generated_at": "2025-01-28T10:30:00Z", "segments": { "watches": { "momentum": "positive", "volume": "above_average", "sentiment": "bullish", "signal_strength": 0.82 }, "art": { "momentum": "neutral", "volume": "average", "sentiment": "neutral", "signal_strength": 0.54 }, "wine": { "momentum": "positive", "volume": "high", "sentiment": "bullish", "signal_strength": 0.78 } }, "alerts": [ { "type": "breakout", "segment": "watches", "message": "Rolex sports models showing strong upward momentum", "severity": "opportunity" } ], "market_scout_validated": true } } ``` ### GET /signals/{segment} Get detailed signals for a specific segment. ``` GET https://api.prophetic.ai/v1/signals/watches
Response
json
{ "segment": "watches", "signals": { "price": { "trend": "upward", "change_7d": "+2.3%", "change_30d": "+5.8%", "change_90d": "+8.1%" }, "volume": { "level": "above_average", "change_vs_avg": "+34%", "transaction_count_30d": 12847 }, "momentum": { "direction": "positive", "strength": 0.82, "duration_days": 45 }, "sentiment": { "overall": "bullish", "score": 0.76, "trend": "improving" }, "top_movers": [ { "brand": "Rolex", "model": "Daytona", "change_30d": "+8.2%" }, { "brand": "Patek Philippe", "model": "Nautilus", "change_30d": "+6.1%" } ] }, "market_scout_validated": true, "generated_at": "2025-01-28T10:30:00Z" } ``` ### GET /signals/alerts Get active market alerts and opportunities. ``` GET https://api.prophetic.ai/v1/signals/alerts
Response
json
{ "alerts": [ { "id": "alert_7f6e5d4c3b2a", "type": "breakout", "severity": "opportunity", "segment": "watches", "title": "Sports watch momentum acceleration", "message": "Rolex and AP sports models showing strong buying pressure", "created_at": "2025-01-28T08:00:00Z", "expires_at": "2025-01-29T08:00:00Z" } ], "count": 1, "generated_at": "2025-01-28T10:30:00Z" } ``` > **Note:** Alerts are time-sensitive and include expiration timestamps. --- ## Portfolio ### Portfolio Endpoints ``` PORTFOLIO ENDPOINTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Endpoint Method Purpose ────────────────────────────────────────────────── /portfolio POST Create portfolio /portfolio/{id} GET Get portfolio analytics /portfolio/{id} PUT Update portfolio /portfolio/{id}/performance GET Performance metrics ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### POST /portfolio Create a new portfolio for tracking. ``` POST https://api.prophetic.ai/v1/portfolio
Request Body
json
{ "name": "Main Collection", "assets": [ { "segment": "watches", "brand": "Rolex", "model": "Daytona", "reference": "126500LN", "purchase_price": 22000, "purchase_date": "2023-06-15" }, { "segment": "wine", "producer": "Domaine de la Romanée-Conti", "vintage": 2018, "quantity": 6, "purchase_price": 18000, "purchase_date": "2022-11-20" } ] }
Response
json
{ "portfolio": { "id": "port_4d5e6f7a8b9c", "name": "Main Collection", "asset_count": 2, "segment_count": 2, "total_invested": 40000, "current_value": 47200, "total_return_percent": 18.0, "created_at": "2025-01-28T10:30:00Z" } } ``` ### GET /portfolio/{id} Get full portfolio analytics. ``` GET https://api.prophetic.ai/v1/portfolio/port_4d5e6f7a8b9c
Response
json
{ "portfolio": { "id": "port_4d5e6f7a8b9c", "name": "Main Collection", "summary": { "asset_count": 2, "segment_count": 2, "total_invested": 40000, "current_value": 47200, "total_return_percent": 18.0, "annualised_return": 11.2, "currency": "EUR" }, "allocation": { "watches": { "value": 26200, "percentage": 55.5 }, "wine": { "value": 21000, "percentage": 44.5 } }, "assets": [ { "asset_id": "PRO-WAT-RLX-126500LN", "current_value": 26200, "purchase_price": 22000, "return_percent": 19.1, "prophetic_score": 82, "momentum": "positive" }, { "asset_id": "PRO-WIN-DRC-2018", "current_value": 21000, "purchase_price": 18000, "return_percent": 16.7, "prophetic_score": 91, "momentum": "positive" } ], "metrics": { "diversification_score": 68, "risk_profile": "moderate", "momentum": "positive", "confidence": 0.91 }, "market_scout_validated": true, "updated_at": "2025-01-28T10:30:00Z" } } ``` ### GET /portfolio/{id}/performance Get detailed performance metrics with benchmark comparison. ``` GET https://api.prophetic.ai/v1/portfolio/port_4d5e6f7a8b9c/performance
Response
json
{ "performance": { "portfolio_id": "port_4d5e6f7a8b9c", "periods": { "1_month": { "return_percent": 2.1, "vs_benchmark": "+0.8%" }, "3_months": { "return_percent": 5.4, "vs_benchmark": "+1.2%" }, "6_months": { "return_percent": 9.8, "vs_benchmark": "+2.1%" }, "1_year": { "return_percent": 18.0, "vs_benchmark": "+3.4%" }, "ytd": { "return_percent": 1.8, "vs_benchmark": "+0.4%" } }, "benchmarks": { "sp500": { "1_year": 14.6 }, "gold": { "1_year": 8.2 }, "luxury_index": { "1_year": 12.4 } }, "best_performer": { "asset_id": "PRO-WAT-RLX-126500LN", "return_percent": 19.1 }, "worst_performer": { "asset_id": "PRO-WIN-DRC-2018", "return_percent": 16.7 }, "generated_at": "2025-01-28T10:30:00Z" } } ``` > **Tip:** Performance is automatically compared against major benchmarks. --- ## Exit Strategies ### Exit Endpoints ``` EXIT ENDPOINTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Endpoint Method Purpose ────────────────────────────────────────────────── /exit POST Get exit strategy /exit/channels GET Available channels by segment ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### POST /exit Get comprehensive exit strategy for an asset. ``` POST https://api.prophetic.ai/v1/exit
Request Body
json
{ "asset_id": "PRO-WAT-RLX-126500LN-2023", "current_value": 26200, "urgency": "flexible" }
Response
json
{ "exit_strategy": { "asset_id": "PRO-WAT-RLX-126500LN-2023", "current_value": 26200, "currency": "EUR", "timing": { "signal": "favourable", "optimal_window": "approaching", "recommendation": "monitor_closely" }, "channels": { "primary": { "name": "Chrono24", "commission_percent": 6.5, "estimated_net": 24507, "timeline_days": "14-21" }, "secondary": { "name": "Christie's", "commission_percent": 20, "estimated_net": 20960, "timeline_days": "60-90" } }, "alternatives": { "lease_back": { "available": true, "yield_percent": 6, "provider": "available_on_request" }, "hold_12_months": { "projected_roi_percent": 10.5, "recommendation": "consider" } }, "confidence": 0.91, "market_scout_validated": true, "generated_at": "2025-01-28T10:30:00Z" } } ``` --- ## Segments ### Segment Endpoints ``` SEGMENT ENDPOINTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Endpoint Method Purpose ────────────────────────────────────────────────── /segments GET List all 10 segments /segments/{segment} GET Segment details ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### GET /segments List all available luxury segments. ``` GET https://api.prophetic.ai/v1/segments
Response
json
{ "segments": [ { "id": "watches", "name": "Luxury Watches", "asset_count": 8420 }, { "id": "art", "name": "Contemporary Art", "asset_count": 12650 }, { "id": "wine", "name": "Fine Wines", "asset_count": 4280 }, { "id": "sneakers", "name": "Collectible Sneakers", "asset_count": 2150 }, { "id": "bags", "name": "Luxury Handbags", "asset_count": 1840 }, { "id": "cards", "name": "Collectible Cards", "asset_count": 1620 }, { "id": "jewellery", "name": "High Jewellery", "asset_count": 980 }, { "id": "automobiles", "name": "Classic Automobiles", "asset_count": 420 }, { "id": "spirits", "name": "Rare Spirits", "asset_count": 890 }, { "id": "real_estate", "name": "Prestige Real Estate", "asset_count": 340 } ], "total_assets": 33590, "accuracy": "91%" } ``` ### GET /segments/{segment} Get detailed segment information. ``` GET https://api.prophetic.ai/v1/segments/watches
Response
json
{ "segment": { "id": "watches", "name": "Luxury Watches", "asset_count": 8420, "brands": ["Rolex", "Patek Philippe", "Audemars Piguet", "Omega", "..."], "data_depth": "decades", "calibration_status": "refined", "performance": { "ytd": "+6.2%", "1_year": "+11.8%", "3_year": "+42.1%" }, "momentum": "positive", "liquidity": "high", "avg_prophetic_score": 74, "top_assets": [ { "brand": "Rolex", "model": "Daytona", "score": 86 }, { "brand": "Patek Philippe", "model": "Nautilus 5711", "score": 92 } ], "active_apis": ["Chrono24", "Rebag"], "market_scout_validated": true } } ``` --- ## Response Codes ### HTTP Status Codes ``` HTTP STATUS CODES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Code Status Description ────────────────────────────────────────────────── 200 OK Successful request 201 Created Resource created 400 Bad Request Invalid parameters 401 Unauthorised Invalid or expired token 403 Forbidden Insufficient permissions 404 Not Found Resource not found 429 Too Many Requests Rate limit exceeded 500 Internal Error Server error ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Error Response Format
json
{ "error": { "code": 400, "type": "validation_error", "message": "Invalid segment specified", "field": "segment", "allowed_values": ["watches", "art", "wine", "sneakers", "bags", "cards", "jewellery", "automobiles", "spirits", "real_estate"], "documentation": "https://docs.prophetic.ai/api/segments" } } ``` > **Note:** All errors include actionable information for resolution. --- ## Summary ### Complete Endpoint List ``` COMPLETE ENDPOINT LIST ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Authentication POST /auth/token POST /auth/refresh Valuations POST /valuations GET /valuations/{id} POST /valuations/batch Scores POST /scores POST /scores/breakdown Projections POST /projections GET /projections/{id} Signals GET /signals GET /signals/{segment} GET /signals/alerts Portfolio POST /portfolio GET /portfolio/{id} PUT /portfolio/{id} GET /portfolio/{id}/performance Exit POST /exit GET /exit/channels Segments GET /segments GET /segments/{segment} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
json
{ "endpoints_summary": { "total_endpoints": 20, "categories": 8, "base_url": "https://api.prophetic.ai/v1", "authentication": "Bearer token", "format": "JSON", "accuracy": "91%", "assets": "32,000+" } }
Note: For code examples and integration guides, see SDKs & Tools.
Need help? Contact Support
Join our Discord Community
Questions? Contact Sales