The institutional data layer for the global art market.

Quickstart

Make your first authenticated request in under a minute. The example below fetches the top 10 artists ranked by total auction sales.

# List the top 10 artists by total sales
curl "https://api.liveart.ai/v1/artists?limit=10&sort_by_total_sales=desc&is_top=true" \
  -H "Authorization: Bearer $LIVEART_API_KEY" \
  -H "Accept: application/json"

Response (truncated)

{
  "artists": [
    {
      "id": 142,
      "uid": "pablo-picasso",
      "name": "Pablo Picasso",
      "nationality": "Spanish",
      "birth": 1881,
      "death": 1973,
      "total_sales": 8214039715,
      "market_cap": 12480000000,
      "price_momentum_percentage_12mo": 7.4,
      "artworks_count": 36214
    }
  ],
  "total": 1287,
  "limit": 10,
  "offset": 0
}

Authentication

The LiveArt API uses HTTP bearer tokens. Pass your API key in the Authorization header on every request:

Authorization: Bearer la_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keys are issued per organization and scoped to a plan tier (Starter / Growth / Enterprise). Treat your key like a password — never embed it in client-side code, mobile bundles, or public repositories.

Public (unauthenticated) endpoints

Two endpoints are intentionally public so you can share data without exposing your key:

• GET /v1/artworks/shared/{token} — view a shared artwork list
• GET /v1/lots/shared/{token} — view a shared lot list

See Sharing & collaboration.

Authenticated vs. public response shapes

The list endpoints (/v1/artists, /v1/artworks, /v1/lots, /v1/sales) return two different object shapes depending on the caller. An authenticated request gets the full schema; an unauthenticated (or insufficiently-entitled) request gets a reduced *Public schema with the financial and proprietary fields removed. Build your clients to tolerate both — the OpenAPI spec models each 200 as an anyOf of the full and public schema.

Base URL & versioning

All endpoints are served from a single base host. Versioning is in the URL path; we will introduce /v2 only for breaking changes and run both versions in parallel for at least 12 months.

https://api.liveart.ai/v1/<resource>

Additive, backwards-compatible changes (new optional query parameters, new fields in responses, new enum values) may be introduced at any time. Build your clients to ignore unknown fields.

Pagination

List endpoints are paginated using a classic limit / offset pattern.

Responses include either a total (for resources where total count is known and cheap to compute) or has_more (for high-cardinality resources like /v1/lots). Use whichever the endpoint returns to drive your UI pager.

GET /v1/artworks?limit=50&offset=100   # page 3 of 50

Filtering operators

List endpoints support a rich, consistent filter grammar built from suffixes appended to field names. Combine as many as you need — they're AND'ed together.

Worked example: blue-chip post-war works coming up at Sotheby's NY

curl "https://api.liveart.ai/v1/lots?\
status=upcoming&\
sale_auction_house_id=1&\
sale_location__in=New%20York&\
hammer_price_estimate_max_usd__gte=1000000&\
creation_year__gte=1945&creation_year__lte=1980&\
sort=HAMMER_PRICE_ESTIMATE_MAX_DESC&\
limit=50" \
  -H "Authorization: Bearer $LIVEART_API_KEY"

Sorting

Each list endpoint accepts a sort query parameter that takes one of an enumerated set of values. The convention is FIELD_DIRECTION:

• Artworks — NAME_ASC, NAME_DESC, CREATION_YEAR_ASC, CREATION_YEAR_DESC, SALE_DATE_ASC, SALE_DATE_DESC, SIZE_ASC, SIZE_DESC
• Lots — NUMBER_ASC, NUMBER_DESC, SALE_DATE_ASC, SALE_DATE_DESC, CREATION_YEAR_ASC/DESC, HAMMER_PRICE_ESTIMATE_MIN_ASC/DESC, HAMMER_PRICE_ESTIMATE_MAX_ASC/DESC
• Sales — ID_ASC/DESC, START_DATETIME_ASC/DESC, END_DATETIME_ASC/DESC, DATE_ASC/DESC
• Artists — use sort_by_total_sales or sort_by_market_cap with values asc / desc

Currencies

All monetary fields are returned natively in the sale's source currency and normalized to USD. Pass preferred_currency on most list/detail endpoints to additionally receive values converted to a third currency of your choice using daily reference rates.

Supported values for preferred_currency:

USD · GBP · EUR · CHF · JPY · CNY · HKD · SGD · TWD · KRW · INR · AUD · CAD · NZD · NOK · RUB

The PriceSchema object on every priced resource contains parallel sets of fields:

List supported currencies

Errors

The API uses standard HTTP status codes. Validation errors are returned with full FastAPI-style detail arrays so you can pinpoint the offending field.

Validation error example

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 100",
      "type": "less_than_equal",
      "input": "500",
      "ctx": { "le": 100 }
    }
  ]
}

Data Units

The LiveArt API uses an internal metering currency called Data Units (DU)to track consumption against your plan's allowance. Every successful authenticated request consumes DUs. Your remaining balance is returned in the response headers on every call.

How DU cost is calculated

DU = base_cost + (per_record_cost × records_returned)

• base_cost is a fixed per-call cost that covers authentication, query planning, and serialization overhead.
• per_record_cost is the incremental cost per record in the response body.
• records_returned is the number of records actually returned.

Core rules

• Requests that return a 4xx or 5xx response consume no DUs. You are never metered for failed calls.
• Requests that return zero results still consume base_cost — the query was executed.
• Write operations (POST, DELETE) are charged base_cost only.
• Follow, unfollow, and share operations are not metered. DU cost is 0.
• Unauthenticated endpoints (shared tokens, healthcheck) are not metered.

DU cost per endpoint

Single-record lookups and computed endpoints

List and search endpoints

Reference data

Not metered (0 DU)

• All follow and unfollow operations (POST and DELETE on /follow endpoints)
• All share operations (POST /v1/artworks/share, POST /v1/lots/share)
• Shared-token retrieval (GET /v1/artworks/shared/{token}, GET /v1/lots/shared/{token})
• GET /v1/usage
• GET /healthcheck

DU values are periodically reviewed against actual infrastructure cost. Material changes are announced via the changelog with at least 30 days notice.

Worked examples

Response headers

Every successful authenticated response includes the following headers:

These headers are exposed to browser clients via CORS. Response bodies are never modified to include DU information — consumption data lives in headers only.

The /v1/usage endpoint

For aggregated consumption queries, call:

curl https://api.liveart.ai/v1/usage \
  -H "Authorization: Bearer <your-api-token>"

Query parameters

Response fields

• Total DUs consumed in the requested window
• Current entitlement and remaining balance
• Period start and end dates
• Projected end-of-period consumption based on run rate
• Breakdown series when group_by is supplied

Approaching your allowance

• At 80%of your period allowance, we'll contact you with your current consumption, projected end-of-period usage, and an invitation to discuss upgrade options.
• At 100%of your period allowance, we'll contact you and Customer Success will reach out to align on a tier that matches your usage pattern.

LiveArt reserves the right to take appropriate action on accounts that materially exceed their plan's DU allowance or that demonstrate usage patterns inconsistent with good-faith use. In practice, we work with customers collaboratively — notifications come first, conversations come second, and other actions are a last resort reserved for cases involving abuse, scraping, or sustained non-response. Customers operating in good faith have nothing to worry about.

If you have questions about your allowance or want to discuss a tier change, email api@liveart.ai.

Resource overview

The API exposes the following core resources. Every endpoint is documented below with its parameters, a real request, and a representative response.

Artists

Biographical and market data on the artists tracked by LiveArt — including total sales, market cap, 12-month price momentum, and a follow mechanism so you can build personalized feeds.

List artists

Get a single artist

{
  "id": 142,
  "uid": "jean-michel-basquiat",
  "name": "Jean-Michel Basquiat",
  "nationality": "American",
  "birth": 1960,
  "death": 1988,
  "bio": "American Neo-expressionist artist...",
  "total_sales": 3214000000,
  "market_cap": 5840000000,
  "max_price": 110487500,
  "price_momentum_percentage_12mo": 12.4,
  "artworks_count": 1842,
  "recent_lots_count": 37,
  "is_followed": true,
  "photo_thumbnail_url": "https://cdn.liveart.ai/..."
}

Artist price chart

{
  "resolution": "monthly",
  "unit": "index",
  "currency": "USD",
  "series": [
    {
      "id": "liveart_index",
      "label": "LiveArt Index",
      "data": [
        { "time": "2020-01-01", "value": 100.0 },
        { "time": "2020-02-01", "value": 102.4 },
        { "time": "2020-03-01", "value": 98.7 }
      ]
    }
  ]
}

Related artists

Follow / unfollow

Analytics

A suite of artist-level analytics endpoints powering the LiveArt terminal — sell-through over time, risk-adjusted returns, repeat-sale performance, and career-path distributions. Each endpoint is keyed by artist_id and returns time-series or grouped data ready to feed a chart.

Artist events

Sales volume

Sharpe ratio

Career path — by artwork count

Career path — by LiveArt estimate

Returns vs. holding period

Compound annual returns by year

Artworks

Each artwork is a unique, deduplicated work — distinct from the lots in which copies of it appear. The artwork object carries the LiveArt Estimate™ AI price prediction, 12- and 24-month momentum, and the full canonical description.

List artworks

The most powerful endpoint in the API. Filter on more than 50 dimensions across artist, physical attributes, market state, sale context, and price.

Selected query parameters

Example: Basquiat works estimated $1M–$5M coming up in the next 90 days

curl "https://api.liveart.ai/v1/artworks?\
artist_id=142&\
last_lot_status=upcoming&\
current_estimated_price__gte=1000000&\
current_estimated_price__lte=5000000&\
date_last_upcoming__gte=2026-04-15&\
date_last_upcoming__lte=2026-07-15&\
sort=SALE_DATE_ASC&\
with_images=true" \
  -H "Authorization: Bearer $LIVEART_API_KEY"

Response shape

{
  "items": [
    {
      "id": 9012345,
      "uid": "jmb-untitled-1982-skull",
      "slug": "untitled-1982",
      "last_lot_status": "upcoming",
      "date_last_upcoming": "2026-05-14",
      "currency": "USD",
      "current_estimated_price": 3850000,
      "current_estimated_price_min": 3200000,
      "current_estimated_price_max": 4500000,
      "price_momentum_12mo": 0.124,
      "price_change_12mo": 421000,
      "description": { "name": "Untitled", "materials": "acrylic and oilstick on canvas", "creation_year": 1982 },
      "price": { "hammer_estimate_min_usd": 3200000, "hammer_estimate_max_usd": 4500000 }
    }
  ],
  "total_count": 7,
  "limit": 20,
  "offset": 0
}

# Default — fills a square box, crops the work:
https://images.liveart.io/cdn-cgi/image/width=240,height=240,fit=cover,quality=85,format=auto/images/230552980/a13ac2b0...

# Rewrite fit=cover -> fit=contain for the full, uncropped work:
https://images.liveart.io/cdn-cgi/image/width=240,height=240,fit=contain,quality=85,format=auto/images/230552980/a13ac2b0...

Artwork price chart

Similar artworks

Editions

CAGR

Recommended artworks

Follow / unfollow

Lots

A lot is a single offering at a single sale. Many lots can point at the same underlying artwork (re-sales, multiple editions). Lot endpoints share most filters with /v1/artworks but add lot-specific fields like hammer price, premium, lot number, and sale context.

List lots

Single lot response (excerpt)

{
  "id": 81472019,
  "lot_num": "24A",
  "status": "sold",
  "auction_house_id": 1,
  "auction_house_name": "Sotheby's",
  "sale_id": 90217,
  "is_top": true,
  "reserve_mark": true,
  "third_party_mark": false,
  "price": {
    "currency": "USD",
    "hammer": 3200000,
    "hammer_estimate_min": 2500000,
    "hammer_estimate_max": 3500000,
    "premium": 3920000,
    "hammer_usd": 3200000,
    "premium_usd": 3920000
  },
  "artwork": { "id": 9012345, "name": "Untitled", "creation_year": 1982 },
  "sale":    { "id": 90217, "name": "Contemporary Evening Auction", "location": "New York" }
}

Follow lots

Sales

A sale is an auction session — typically multiple lots offered together over a single day or evening. Sale objects carry aggregate totals (hammer total, premium total, sell-through ratios) once concluded.

List sales

Sale aggregate fields

Concluded sales include rich aggregate metrics — perfect for sale-recap dashboards and benchmarking:

• cumulative_total, hammer_total, premium_sold_total — top-line totals (also _usd_zeroied and _preferred variants)
• hammer_low_estimate, hammer_high_estimate — pre-sale estimate envelope
• lots_count, lots_count_not_sold, lots_count_sold_above_estimations, _within_, _below_ — sell-through breakdown
• is_bids_streaming — whether LiveArt has a live feed of incoming bids

Collectables

A collectableis a work in a user's own collection — the building block of the LiveArt portfolio/inventory tools. Unlike the read-only market resources above, collectables are fully read-write: create a record, attach an image, and maintain its acquisition details, appraisals, provenance chain, and private sale history. Every collectable is scoped to the authenticated user; there is no public variant.

List & create collectables

# multipart/form-data — image optional
curl -X POST https://api.liveart.ai/v1/collectables \
  -H "Authorization: Bearer $LIVEART_API_KEY" \
  -F "artist_id=142" \
  -F "category_id=1" \
  -F "edition_unique_type=unique" \
  -F "image=@/path/to/work.jpg"

{
  "id": 4821,
  "uid": "c_8f3a2b1d",
  "title": "Untitled (Skull)",
  "artist_id": 142,
  "artist_name": "Jean-Michel Basquiat",
  "category_id": 1,
  "category_name": "Painting",
  "creation_year": 1982,
  "current_estimated_price": 3850000,
  "machine_estimated_price": 3720000,
  "manual_price_value": null,
  "selected_price_type": "machine",
  "price_momentum_12mo": 0.124,
  "condition": "good",
  "signature": "signed verso",
  "measurements_unit": "cm",
  "measurements_height": 183,
  "measurements_width": 173,
  "material_ids": [4, 11],
  "substrate_ids": [2],
  "current_location": "New York, NY",
  "image_thumbnail_url": "https://cdn.liveart.ai/..."
}

Get, update & delete

Image

Acquisition details

Appraisals

A time-stamped valuation history (insurance, market, etc.). Each record is an AppraisalSchema with value + value_usd, type, date, and company_name.

POST /v1/collectables/4821/appraisals
{
  "type": "insurance",
  "value": 4200000,
  "currency": "USD",
  "date": "2026-03-01",
  "company_name": "AXA Art",
  "is_best_guess": false
}

Provenance

The ownership chain — an ordered list of ProvenanceSchema records (owner, location, year_from / year_to, and is_up_to_present for the current holder).

Sale records

Private sale events for the work — a CollectableSaleSchema (value + value_usd, date, location, type, optional auction_house_id and seller_name). Distinct from the public /v1/sales auction sessions.

Auction Houses

[
  { "id": 1, "name": "Sotheby's",    "slug": "sothebys",    "priority_order": 1, "is_live": true },
  { "id": 2, "name": "Christie's",   "slug": "christies",   "priority_order": 2, "is_live": true },
  { "id": 3, "name": "Phillips",     "slug": "phillips",    "priority_order": 3, "is_live": true }
]

Auction Locations

Categories

Reference data

Controlled vocabularies for the physical attributes of a work. These back the condition/medium selectors in the collection tools and the structured *_ids fields on CollectableSchema. Each returns a flat array of { id, name, label } and accepts an optional name query parameter for substring/autocomplete search.

[
  { "id": 4,  "name": "oil",    "label": "Oil" },
  { "id": 11, "name": "canvas", "label": "Canvas" },
  { "id": 27, "name": "bronze", "label": "Bronze" }
]

Plans

Market

{
  "art_data": [
    { "time": "2020-01-01", "value": 100.0 },
    { "time": "2021-01-01", "value": 118.6 },
    { "time": "2022-01-01", "value": 131.2 }
  ],
  "finance_data": [
    {
      "id": "SNP500",
      "label": "S&P 500",
      "data": [
        { "time": "2020-01-01", "value": 100.0 },
        { "time": "2021-01-01", "value": 116.3 }
      ]
    }
  ]
}

Sharing & collaboration

Two POST endpoints turn a private list of artworks or lots into a tokenized URL that can be viewed without authentication — ideal for sending an advisor's pre-sale recommendations to a collector.

Health check

Schemas

The API returns a small number of well-defined object types. The most important ones:

Field-level definitions for every schema are in the OpenAPI spec.

OpenAPI specification

The full machine-readable specification is published at:

https://api.liveart.ai/openapi.json

The spec is OpenAPI 3.1.0 and works out-of-the-box with code generators — Swagger Codegen, OpenAPI Generator, openapi-typescript, openapi-python-client, etc. We recommend regenerating clients on each release of your application.

Generate a typed Python client

pipx install openapi-python-client
openapi-python-client generate \
  --url https://api.liveart.ai/openapi.json \
  --meta poetry

Generate TypeScript types

npx openapi-typescript https://api.liveart.ai/openapi.json -o ./liveart.d.ts

Changelog

The API follows additive, backwards-compatible evolution within /v1. We publish a changelog with every release.

Need help?

Email api@liveart.ai for support, enterprise pricing, or questions about embedding LiveArt data in production systems.