API Reference

The Impossival API accepts asset descriptions and returns valuation estimates with confidence intervals, market comparables, and liquidity assessments.

Quickstart

The Impossival API provides programmatic access to our asset valuation engine. Send a text description of any asset—collectibles, fine art, vintage cars, wine, or other alternative investments—and receive a market value estimate with confidence intervals.

How it works

Submit an asset description via POST /v1/value
Our model analyzes the description, identifies the asset, and researches market comparables
Receive a valuation with estimate, confidence range, and supporting data

Get started

Create an account to access the dashboard
Generate an API key from your dashboard
Make your first request using the example on the right

Base URL: https://api.impossival.com

Interactive docs: /docs (Swagger), /redoc

Example: Value an asset

BASH

curl -X POST "https://api.impossival.com/v1/value" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_description": "1967 Fender Stratocaster in sunburst finish"}'

Response

JSON

{
  "valuation_id": "550e8400-e29b-41d4-a716-446655440000",
  "asset_description": "1967 Fender Stratocaster...",
  "estimate": 28500,
  "range": { "low": 22000, "high": 35000 },
  "confidence": 0.78,
  "asset_category": "instruments",
  "liquidity_tier": "weeks"
}

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header of all requests.

Generate API keys from your account dashboard. Keys are prefixed with impv_.

Key management

Create multiple keys for different environments
Revoke keys instantly from your dashboard
Keys can be scoped to specific rate limits

Authorization header

HEADER

Authorization: Bearer impv_your_api_key_here

Example with cURL

BASH

curl -H "Authorization: Bearer impv_abc123..." \
  https://api.impossival.com/v1/value

Requests

Submit a POST request to /v1/value with an asset description to receive a valuation.

Request Body

Use application/json encoding:

Field	Description
asset_description	Required. 10–2,000 characters.
image	Optional. Object with `data` (base64) and `media_type`.
skip_cache	Optional. Force fresh valuation. Default: false.
timeout	Optional. 5–120 seconds.

CURL

curl -X POST "https://api.impossival.com/v1/value" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_description": "1967 Fender Stratocaster electric guitar in sunburst finish. Original pickups, minor wear on fretboard, includes original hardshell case."
  }'

# With optional image for vision-enhanced valuation:
curl -X POST "https://api.impossival.com/v1/value" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_description": "Vintage guitar, see photo for details",
    "image": {
      "data": "<base64-encoded-image-data>",
      "media_type": "image/jpeg"
    }
  }'

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

Endpoints

Submit an asset description (with optional base64-encoded 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 and comprehensive analysis.

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

Request

JSON

// Content-Type: application/json

{
  "asset_description": string,  // Required. 10-2,000 characters.
  "image": {                    // Optional. For vision-enhanced valuation.
    "data": string,             // Base64-encoded image data
    "media_type": string        // "image/jpeg", "image/png", or "image/webp"
  },
  "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,
  "market_research_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

Pagination

The /valuations/history endpoint supports pagination through query parameters.

Parameters

limit	Number of results (1–500, default: 100)
offset	Skip this many results (default: 0)
category	Filter by asset category

Results are returned in reverse chronological order (newest first).

BASH

GET /v1/valuations/history?limit=10&offset=0

# Response
{
  "valuations": [
    {
      "valuation_id": "550e8400-e29b-...",
      "asset_description": "1967 Fender...",
      "estimate": 28500,
      "created_at": "2025-01-15T10:30:00Z"
    },
    ...
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}

Null Fields

To reduce response payload size, fields with null values are omitted from the response. This keeps payloads clean when optional analysis fields aren't applicable.

Optional Fields

These fields appear only when relevant:

vision_enhanced_description — only with image input
market_research_context — market research data
uncertainty_analysis — detailed risk factors
attribution_analysis — value driver breakdown

Always check for field existence before accessing optional properties.

JSON

// With image input
{
  "asset_description": "Enhanced description...",
  "original_description": "User's input",
  "vision_enhanced_description": "AI-enhanced...",
  ...
}

// Without image input
{
  "asset_description": "User's input",
  // original_description: omitted (null)
  // vision_enhanced_description: omitted (null)
  ...
}

Errors

The API returns errors in a consistent JSON format with a descriptive message.

HTTP Status Codes

200	Success
400	Bad request or policy violation
401	Missing or invalid API key
413	Request body too large (max 50KB)
422	Validation error
429	Rate limit exceeded
500	Server error
503	Service unavailable

JSON

// Error response format
{
  "detail": "Error message describing what went wrong"
}

// Policy violation example
{
  "detail": "Request blocked: illegal items are not supported"
}

// Validation error example
{
  "detail": "asset_description must be 10-2000 characters"
}

Rate Limits

Limits are applied per API key. Exceeding limits returns 429.

Usage Tiers

Tier	Rate	Daily Cap
Anonymous	5/minute	—
Free (API key)	2/minute	10/day
Pro	Contact us	Unlimited

Request Limits

Max request size	50 KB
Description length	10–2,000 characters

Note: Email verification is required before creating API keys. Daily caps reset at midnight UTC.

BASH

# Rate limit headers in response
X-RateLimit-Limit: 2
X-RateLimit-Remaining: 1
X-RateLimit-Reset: 1705320600

# Rate limit exceeded (per-minute)
{
  "detail": "Rate limit exceeded. Please wait before making another request.",
  "retry_after_seconds": 60
}

# Daily cap exceeded
{
  "detail": "Daily request limit exceeded (10/10). Resets at midnight UTC (in 3 hours 45 minutes). Contact us for higher limits."
}

Content Policy

Requests are screened for policy compliance. Blocked requests return 400:

Illegal items (drugs, stolen goods, counterfeit products)
Human exploitation (trafficking, organ sales)
Endangered species products
Items glorifying hate groups

Allowed: Collectible weapons (antique firearms, historical swords, military memorabilia).

JSON

// Policy violation response
{
  "detail": "Request blocked: endangered species products are not supported",
  "category": "endangered_species"
}