API REFERENCE

API Documentation

Integrate AI-powered asset valuations into your applications with our REST API. Generate value estimates for any asset through multi-agent consensus with real-time market grounding.

GETTING STARTED

Quick Start

Your RequestPOST + API Key

/api/v1/valueMulti-agent + grounding

Valuation ResultEstimate + market data

Make a POST request to /api/v1/value with your API key and asset description to get a valuation:

CURL

curl -X POST "http://localhost:8000/api/v1/value" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "asset_description=1967 Fender Stratocaster electric guitar in sunburst finish. Original pickups, minor wear on fretboard, includes original hardshell case. Serial number verified, all electronics functional."

# With optional image for vision-enhanced valuation:
curl -X POST "http://localhost:8000/api/v1/value" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "asset_description=Vintage guitar, see photo for details" \
  -F "image=@guitar.jpg"

Example Response

JSON

{
  "valuation_id": "550e8400-e29b-41d4-a716-446655440000",
  "valuation_timestamp": "2025-01-15T10:30:00Z",
  "currency": "USD",
  "asset_description": "1967 Fender Stratocaster...",
  "asset_type": "non_cash_flowing",
  "asset_category": "instruments",
  "classification_reasoning": "Vintage electric guitar...",
  "estimate": 28500,
  "range": {
    "low": 22000, "high": 35000,
    "low_multiple": 0.77, "high_multiple": 1.23
  },
  "confidence": 0.78,
  "distribution": {
    "p10": 22000, "p25": 25000, "p50": 28500,
    "p75": 32000, "p90": 35000
  },
  "liquidity_tier": "weeks",
  "recommended_refresh_days": 90,
  "methodology_summary": "Factor-based valuation using...",
  "valuation_summary": {
    "participants": 1,
    "final_estimates": [28500],
    "estimates": [...],
    "convergence": [...]
  },
  "cost": {
    "total_input_tokens": 8500,
    "total_output_tokens": 2100,
    "total_cost_usd": 0.018
  }
}

// Note: null fields are omitted from response for cleaner payloads

SECURITY

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header:

HEADER

Authorization: Bearer impv_your_api_key_here

API Key Types

•User API Keys — Generated from your account dashboard. Start with impv_
•Internal Keys — For frontend-to-backend communication (configured in environment)

Public endpoints that don't require authentication:/health,/docs,/redoc

LIMITS

Rate Limiting

Rate limits protect the API from abuse and ensure fair access. Limits are applied per API key or IP address.

Standard Valuations

5 requests/minute

With skip_cache=true

1 request/minute

Max Request Size

50 KB

Description Length

10-2,000 chars

POLICY

Content Policy

Requests are screened for ethical policy violations. The following categories will be blocked with a 400 response:

• Illegal items — Drugs, stolen goods, counterfeit products
• Human exploitation — Trafficking, organ sales, slavery-related
• Endangered species — Protected wildlife products
• Controversial historical — Items glorifying hate groups

Note: Collectible weapons (antique firearms, historical swords, military memorabilia) are allowed and will be valued appropriately.

Blocked Request Response

JSON

{
  "error": "valuation_blocked",
  "category": string,     // "illegal_items"|"human_exploitation"|
                          // "endangered_species"|"controversial_historical"
  "reason": string,       // Human-readable explanation
  "policy_url": string | null
}

CONFIGURATION

Base URL

All API endpoints are relative to the base URL:

http://localhost:8000

Replace with your production URL when deploying. Interactive API documentation is also available at /docs (Swagger UI).

API REFERENCE

Endpoints

Submit an asset description (with optional image) to receive a value estimate using factor-based valuation with LLM-extracted factors. If an image is provided, a vision model will analyze it and enhance the description. Includes market research grounding and comprehensive analysis.

Rate limit: 5/min anonymous, 60/min with API key (custom limits may apply)

Request

JSON

// Content-Type: multipart/form-data

Form Fields:
  asset_description: string   // Required. 10-2,000 characters.
  image: File | null          // Optional. Image file (JPEG, PNG, WebP) for vision-enhanced valuation.
  timeout: number | null      // Optional. 5-120 seconds.
  skip_cache: boolean         // Optional. Force fresh valuation. Default: false

Response

JSON

{
  // === Fintech Integration Fields ===
  "valuation_id": string,           // UUID for tracking/audit
  "valuation_timestamp": string,    // ISO 8601 timestamp
  "currency": "USD",

  // === Core Valuation Fields ===
  "asset_description": string,      // Description used for valuation (may be vision-enhanced)
  "original_description"?: string,  // User's original description (only if image provided)
  "vision_enhanced_description"?: string,  // Vision-enhanced description (only if vision phase was used)
  "asset_type": "cash_flowing" | "non_cash_flowing",
  "asset_category": string,
  "classification_reasoning": string,
  "estimate": number,               // Point estimate (median)
  "range": {
    "low": number,                  // 10th percentile
    "high": number,                 // 90th percentile
    "low_multiple": number,         // Low as multiple of estimate
    "high_multiple": number         // High as multiple of estimate
  },
  "confidence": number,             // 0-1 based on convergence
  "distribution": {
    "p10": number, "p25": number, "p50": number,
    "p75": number, "p90": number
  },
  
  // === Market & Risk Indicators ===
  "liquidity_tier": string,         // "immediate"|"days"|"weeks"|"months"|"illiquid"
  "recommended_refresh_days": number,
  "methodology_summary": string,
  "market_timing_status"?: string,  // "appreciating"|"stable"|"depreciating"
  "refresh_urgency"?: string,       // Volatility classification
  "average_annual_change_rate"?: number,

  // === Analysis Fields (omitted when null) ===
  "description_quality"?: object,
  "uncertainty_analysis"?: object,
  "attribution_analysis"?: object,
  "framework_used"?: object,
  "grounding_context"?: object,     // Market research data
  
  // === Cost & Timing ===
  "cost": {
    "total_cost_usd": number,
    "total_duration_ms": number,
    "total_llm_calls": number,
    "total_input_tokens": number,
    "total_output_tokens": number,
    "phases": object
  },
  
  // === Valuation Details ===
  "valuation_summary": {
    "participants": number,
    "final_estimates": number[],
    "estimates": EstimateDetail[],
    "convergence": ConvergencePoint[],
    "value_min": number, "value_max": number,
    "value_p25": number, "value_p75": number,
    "convergence_percent"?: number
  }
}

// Note: Fields marked with ? are optional and omitted when not set

RESPONSES

Error Handling

The API returns standard HTTP status codes and error messages in a consistent format:

JSON

{
  "detail": "Error message describing what went wrong"
}

200Successful request

400Invalid request / Policy violation

401Missing or invalid API key

413Request body too large

422Validation error

429Rate limit exceeded

503Database unavailable

500Server error

BEST PRACTICES

Notes

Caching

Valuation results are cached for identical descriptions (when using default parameters). Use skip_cache=true to force fresh valuations.

Response Time

Valuations typically take 5-15 seconds depending on market research complexity. Cached valuations return instantly.

Description Quality

More detailed descriptions yield more accurate valuations. Include condition, provenance, rarity, and any verifiable details.

Market Grounding

Responses include real-time market research with comparable sales, price ranges, and market trends in the grounding_context field.

Valuation IDs

Each response includes a unique valuation_id (UUID) for tracking and audit trails. Store these for reference.

Refresh Guidance

Check recommended_refresh_days and refresh_urgency for guidance on when to re-value volatile assets.