API
Getting Started
Start building with Prophetic API in under 5 minutes. Authentication, first call, and core concepts to integrate luxury intelligence.
Introduction
The Prophetic API provides programmatic access to luxury asset valuations, Prophetic Scores, market signals, and ROI projections across all 10 segments. This guide walks you through authentication, your first API call, and core concepts to start building with luxury intelligence.
Whether you're building wealth management dashboards, investment platforms, or custom analytics tools, the API delivers the same 91% accuracy available through our web interface.
Note: API access requires an ORACLE subscription. Contact our team to get started.
API Overview
Intelligence Access
json
{ "api": { "version": "v1", "base_url": "https://api.prophetic.ai", "format": "JSON", "authentication": "Bearer_token", "accuracy": "91%", "assets": "32,000+", "segments": 10 } } ``` ### Core Capabilities | Capability | Endpoint | Description | |------------|----------|-------------| | **Valuations** | `/valuations` | Real-time asset pricing | | **Scores** | `/scores` | Prophetic Score (0-100) | | **Projections** | `/projections` | 3-scenario ROI modelling | | **Signals** | `/signals` | Market intelligence | | **Portfolio** | `/portfolio` | Holdings analytics | > **Tip:** All endpoints return consistent JSON structures for easy integration. --- ## Quick Start ### Integration Flow ``` GETTING STARTED FLOW ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Step 1 Step 2 Step 3 │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Get │ ───▶ │ Auth │ ───▶ │ Call │ │ API Key │ │ Request │ │Endpoints│ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ Access Token JSON Response │ │ │ └────────────────┴────────────────┘ │ ▼ ┌─────────────────────┐ │ Build with Luxury │ │ Intelligence │ └─────────────────────┘ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ### Quick Start Summary | Step | Action | Time | |------|--------|------| | **1** | Obtain API credentials (ORACLE subscription) | — | | **2** | Authenticate and retrieve access token | ~1 minute | | **3** | Make your first valuation request | ~2 minutes | > **Note:** Most developers make their first successful call within 5 minutes. --- ## Authentication ### Getting Your Token ``` AUTHENTICATION FLOW ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Your App Prophetic API │ │ │ POST /auth/token │ │ + client_id │ │ + client_secret │ ├─────────────────────────────────▶│ │ │ │ { access_token, expires_in } │ │◀─────────────────────────────────┤ │ │ │ GET /valuations │ │ Authorization: Bearer {token} │ ├─────────────────────────────────▶│ │ │ │ { valuation_data } │ │◀─────────────────────────────────┤ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Token Request
bash
curl -X POST https://api.prophetic.ai/v1/auth/token \ -H "Content-Type: application/json" \ -d '{ "client_id": "your_client_id", "client_secret": "your_client_secret", "grant_type": "client_credentials" }'
Token Response
json
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "scope": "valuations scores projections signals portfolio" }
Important: Store tokens securely. Never expose credentials in client-side code.
First API Call
Request a Valuation
bash
curl -X POST https://api.prophetic.ai/v1/valuations \ -H "Authorization: Bearer {access_token}" \ -H "Content-Type: application/json" \ -d '{ "segment": "watches", "brand": "Rolex", "model": "Daytona", "reference": "126500LN", "year": 2023, "condition": "excellent" }'
Valuation Response
json
{ "valuation": { "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, "prophetic_score": 82, "momentum": "positive", "market_scout_validated": true, "generated_at": "2025-01-28T10:30:00Z" } } ``` > **Tip:** The response includes valuation range, confidence level, Prophetic Score, and Market Scout validation status in one call. --- ## Core Concepts ### Key Elements ``` API CORE CONCEPTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Concept Description ────────────────────────────────────────────────── Segments 10 luxury categories Asset ID Unique identifier (PRO-XXX-XXX) Prophetic Score Investment rating (0-100) Confidence Prediction reliability (0-1) Momentum Trend direction (▲/●/▼) Horizon Projection timeframe (12/24/36mo) Market Scout AI validation status ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Segments
Code | Segment | Coverage |
|---|---|---|
| Watches | Deep |
| Contemporary Art | Deep (100+ years) |
| Fine Wines | Deep |
| Sneakers | Deep |
| Luxury Bags | Deep |
| Collectible Cards | Deep |
| High Jewellery | Established |
| Classic Automobiles | Established |
| Spirits (Whisky) | Established |
| Prestige Real Estate | Adapted |
Asset ID Format
json
{ "asset_id_format": { "pattern": "PRO-{SEGMENT}-{BRAND}-{REF}-{YEAR}", "example": "PRO-WAT-RLX-126500LN-2023", "components": { "PRO": "Prophetic prefix", "WAT": "Segment code", "RLX": "Brand code", "126500LN": "Reference", "2023": "Year (optional)" } } } ``` > **Note:** Understanding these concepts helps you interpret API responses effectively. --- ## Available Endpoints ### Endpoint Overview ``` API ENDPOINTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Endpoint Method Purpose ────────────────────────────────────────────────── /auth/token POST Get access token /auth/refresh POST Refresh expired token /valuations POST Get asset valuation /valuations/{id} GET Retrieve by ID /scores POST Get Prophetic Score /scores/batch POST Score multiple assets /projections POST ROI projections (3 scenarios) /projections/{id} GET Retrieve projection /signals GET Market signals /signals/{segment} GET Segment-specific signals /portfolio POST Create portfolio /portfolio/{id} GET Portfolio analytics /portfolio/{id} PUT Update portfolio /exit POST Exit strategy analysis ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tip: See the full API Reference for detailed endpoint documentation.
Code Examples
Python
python
import requests # Authentication auth_response = requests.post( "https://api.prophetic.ai/v1/auth/token", json={ "client_id": "your_client_id", "client_secret": "your_client_secret", "grant_type": "client_credentials" } ) token = auth_response.json()["access_token"] # Get valuation with Prophetic Score valuation = requests.post( "https://api.prophetic.ai/v1/valuations", headers={"Authorization": f"Bearer {token}"}, json={ "segment": "watches", "brand": "Rolex", "model": "Daytona", "reference": "126500LN", "year": 2023, "condition": "excellent" } ) data = valuation.json() print(f"Value: €{data['valuation']['estimated_value']['mid']:,}") print(f"Score: {data['valuation']['prophetic_score']}/100") print(f"Momentum: {data['valuation']['momentum']}")
JavaScript
javascript
// Authentication const authResponse = await fetch('https://api.prophetic.ai/v1/auth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ client_id: 'your_client_id', client_secret: 'your_client_secret', grant_type: 'client_credentials' }) }); const { access_token } = await authResponse.json(); // Get valuation with Prophetic Score const valuation = await fetch('https://api.prophetic.ai/v1/valuations', { method: 'POST', headers: { 'Authorization': `Bearer ${access_token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ segment: 'watches', brand: 'Rolex', model: 'Daytona', reference: '126500LN', year: 2023, condition: 'excellent' }) }); const data = await valuation.json(); console.log(`Value: €${data.valuation.estimated_value.mid.toLocaleString()}`); console.log(`Score: ${data.valuation.prophetic_score}/100`); ``` > **Note:** SDKs for Python, JavaScript, and other languages coming soon. --- ## Error Handling ### Common Errors ``` ERROR CODES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Code Error Resolution ────────────────────────────────────────────────── 400 Bad Request Check request body format 401 Unauthorised Refresh your access token 403 Forbidden Check API tier permissions 404 Not Found Verify endpoint and asset ID 429 Rate Limited Reduce request frequency 500 Server Error Retry with exponential backoff ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Error Response Format
json
{ "error": { "code": 401, "type": "unauthorised", "message": "Access token expired", "action": "refresh_token", "documentation": "https://docs.prophetic.ai/api/auth/refresh" } } ``` > **Tip:** All errors include an `action` field suggesting how to resolve the issue. --- ## Rate Limits ### Tier-Based Limits ``` RATE LIMITS BY TIER ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Tier Requests/min Requests/day ────────────────────────────────────────────────── ORACLE Starter 60 5,000 ORACLE Pro 300 50,000 ORACLE Enterprise Custom Custom ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Rate Limit Headers
json
{ "headers": { "X-RateLimit-Limit": "300", "X-RateLimit-Remaining": "255", "X-RateLimit-Reset": "1706442600" } } ``` > **Note:** Rate limit status is included in response headers for every request. --- ## Next Steps ### Continue Building ``` NEXT STEPS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Step Resource ────────────────────────────────────────────────── Full endpoint docs → API Reference Integration guides → Endpoints documentation Code libraries → SDKs & Tools Get help → api@prophetic.ai ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` --- ## Summary ### Getting Started Checklist ``` GETTING STARTED CHECKLIST ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ☐ Obtain API credentials (ORACLE subscription) ☐ Authenticate and retrieve access token ☐ Make your first valuation request ☐ Handle token refresh for long sessions ☐ Implement error handling ☐ Respect rate limits ☐ Explore additional endpoints ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
json
{ "getting_started_summary": { "authentication": "Bearer token", "base_url": "https://api.prophetic.ai/v1", "response_format": "JSON", "accuracy": "91%", "time_to_first_call": "under_5_minutes", "support": "api@prophetic.ai" } }
Note: You're ready to build with luxury intelligence.
Need help? Contact Support
Join our Discord Community
Questions? Contact Sales