Skip to content

LiveArt API · v1

The institutional data layer for the global art market.

Programmatic access to the world's largest structured auction dataset — 30M+ sale records across 1,400+ auction houses, with AI-powered price estimates, artist analytics, and live sale data. Built for collectors, advisors, financial institutions, and developers building the next generation of art-market tooling.

Base URLhttps://api.liveart.ai
Versionv1
AuthBearer token
FormatJSON / OpenAPI 3.1

Evaluating LiveArt as a data source? Start the free API trial: 1,000 Data Units for 14 days, no card. For coverage, licensing, and volume, talk to our team.

Quickstart

Make your first authenticated request in under a minute. The example below lists LiveArt's top artists, ranked by auction sales over the trailing 12 months.

# Top artists, ranked by auction sales over the trailing 12 months
curl "https://api.liveart.ai/v1/artists?limit=10&sort_by=TOTAL_SALES&sort_dir=desc&is_top=true" \
  -H "Authorization: Bearer $LIVEART_API_KEY" \
  -H "Accept: application/json"

Response (truncated)

200 OK · application/json
{
  "artists": [
    {
      "id": 404,
      "uid": "aMCprL",
      "name": "Pablo Picasso",
      "nationality": "Spanish",
      "birth": 1881,
      "death": 1973,
      "total_sales": 463124963,
      "market_cap": 11265772458.130733,
      "price_momentum_percentage_12mo": 5.2735881643174665,
      "artworks_count": 49214
    }
  ],
  "total": 205,
  "limit": 10,
  "offset": 0
}

Authentication

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

HTTP
Authorization: Bearer la-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate and manage your keys in Account → API access. API access requires a LiveArt API plan, an Enterprise agreement, or the one-time free API trial (1,000 Data Units for 14 days, no card). Each key draws on your plan’s Data Unit pool. Treat your key like a password — never embed it in client-side code, mobile bundles, or public repositories.

Public-facing deployments

Embedding the API in a public website, mobile app, or downstream API constitutes data redistribution and requires an Enterprise license. Internal-use Builder plans cannot be used to power public products. Contact [email protected] to upgrade.

Shared links (no key required)

Shared-list links open without a key, so you can pass data on without exposing yours:

  • 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), along with the single-artist, related-artists, and similar-artworks lookups, return two different object shapes depending on the caller. A request with a valid key gets the full schema; a request without a key gets a reduced *Public schema with fewer fields. Build your clients to tolerate both — the OpenAPI spec models each 200 as an anyOf of the full and public schema.

Left out of the public schemas

ArtistPublicSchema omits these fields of the full ArtistSchema: bio, long_bio, artist_index_chart, is_followed, price_momentum_percentage_5y, total_sales_price_median_1yr, and total_sales_lots_1yr. Public artworks omit the LiveArt Estimate™ and price data (current_estimated_price and its range, price_momentum_*, price_change_*, currency, and the price object). Public lots omit the price object, the bid fields, and the auction-house and guarantee fields. Public sales omit auction_url, is_bids_streaming, is_charity, location_id, and is_followed. A request with a valid key returns the full schemas.

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.

URL
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.

Every JSON object response also carries three metadata fields that the samples on this page leave out: _request_id, _timestamp, and _notice. The first two are repeated in the X-LiveArt-Request-Id and X-LiveArt-Timestamp response headers; quote the request id when you contact support.

Pagination

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

ParameterTypeDefaultDescription
limitinteger20–100Number of items per page. Max varies by endpoint (typically 100; up to 1000 for /v1/artists).
offsetinteger0Number of items to skip from the start of the result set.

Every list response echoes limit and offset. The rows and the count come under resource-specific names: /v1/artists returns artists with total; /v1/artworks, /v1/sales, and /v1/collectables return items with total_count; /v1/lots returns items with a has_more flag in place of a count. Use whichever the endpoint returns to drive your UI pager.

Example
GET /v1/artworks?artist_id=3505&limit=50&offset=100   # third page, 50 per page

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.

SuffixMeaningExample
(none)Exact matchartist_id=3505
__inMatch any of. Repeat the param for each value; on numeric and enum fields a comma-separated list works tooartist_id__in=3505&artist_id__in=404
__gteGreater than or equallast_hammer_price_usd__gte=100000
__lteLess than or equalcreation_year__lte=1970
__eqExplicit equality (used for enum-style fields like size)size__eq=big
__ilikeCase-insensitive substring matchname__ilike=evening sale

Dates are written YYYY-MM-DD. Date-time filters (sale_datetime__gte, start_datetime__lte, and the like) take the same date, or a date-time such as 2026-10-05T14:00:00. A value without an offset is read as UTC; one that carries Z or an offset is converted to UTC.

Check the parameter name

Each endpoint accepts the parameter names listed in its table and in the OpenAPI spec, and a suffix is available only where it is listed: artist_id__in exists on /v1/artworks, while /v1/lots takes artist_uid__in. A parameter the endpoint does not define is rejected: the request returns 422, and detail[] names each unknown parameter. Before 2026-10-13 such a parameter was ignored and the request returned 200 without that filter.

Worked example: blue-chip post-war works sold at Sotheby's NY, most recent first

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

Sorting

The artwork, lot, and sale lists accept a sort query parameter that takes one of an enumerated set of values, following the convention FIELD_DIRECTION. Artists use sort_by with a separate sort_dir. A value outside the list returns 422.

  • Artworks — NAME_ASC, NAME_DESC, CREATION_YEAR_ASC, CREATION_YEAR_DESC, SALE_DATE_ASC, SALE_DATE_DESC, SIZE_ASC, SIZE_DESC
  • Lots — RAW_LOT_ID_ASC/DESC, 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 — sort_by (MARKET_CAP, TOTAL_SALES, MAX_PRICE, MEDIAN_1YR, RECENT_LOTS, LOTS_1YR, ARTWORKS, MOMENTUM_12MO, MOMENTUM_5Y, NAME, BIRTH) with sort_dir (asc / desc). The older sort_by_total_sales and sort_by_market_cap parameters are deprecated; use sort_by

Currencies

Auction prices are returned in the sale's own 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. On artworks, LiveArt Estimate™ values (current_estimated_price and its range) are expressed in USD, whatever the currency field beside them says: that field is the currency of the artwork's last lot. With preferred_currency the same values also come converted at today's rate, in current_estimated_price_preferred and its range, and lae_preferred_currency names the currency.

Supported values for preferred_currency:

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

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

Field familyMeaning
hammer / hammer_estimate_min / hammer_estimate_max / premiumNative sale currency (see currency)
*_usdNormalized to USD
*_preferredConverted to the currency you passed in preferred_currency

Currency reference list

GET/v1/currencies

Returns the currencies preferred_currency accepts, with a code, name, and symbol for each: the same list as above, on every endpoint that takes the parameter.

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.

StatusMeaning
200 OKSuccessful request
201 CreatedRecord created — POST on collectables and their appraisal, provenance, and sale records
204 No ContentSuccessful follow, unfollow, or delete, with no body
401 UnauthorizedMissing, invalid, expired, or revoked credentials — the same on every endpoint
403 ForbiddenCredentials accepted, but access to this resource is not allowed. A disabled account answers 403 on every endpoint, for its API keys and its sessions alike, with { "code": "account_disabled", "detail": "…" }; retrying does not help, so contact support
404 Not FoundResource does not exist (or is not accessible to you)
422 Unprocessable EntityValidation error — see detail[] for offending fields. A query parameter the endpoint does not define is one of them
429 Too Many RequestsRequest-rate limit, or a daily or monthly Data Unit limit, reached — wait the number of seconds given in the Retry-After header, then retry
5xxServer error — safe to retry with exponential backoff

Errors other than validation failures carry a single message in detail, for example { "detail": "Artist not found" }.

Validation error example

422 · application/json
{
  "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. Successful authenticated requests to metered endpoints consume DUs, and each metered response reports the cost of that call and your remaining balance in its headers.

How DU cost is calculated

Formula
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

EndpointBasePer record
GET /v1/artists/{artist_id}1—
GET /v1/artists/{artist_id}/chart10—
GET /v1/artworks/{artwork_id}/chart10—
GET /v1/artworks/{artwork_id}/editions21.5
GET /v1/artworks/{artwork_id}/similar101.5
GET /v1/artists/{artist_id}/related101

List and search endpoints

EndpointBasePer record
GET /v1/artists21
GET /v1/artists/followed21
GET /v1/artworks21.5
GET /v1/lots21
GET /v1/lots/followed21
GET /v1/sales21
GET /v1/sales/followed21

Reference data

EndpointBasePer record
GET /v1/categories1—
GET /v1/auction-houses1—

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

RequestRecordsCalculationDU
GET /v1/artists/123111
GET /v1/artists202 + (1 × 20)22
GET /v1/lots?artist_id=123502 + (1 × 50)52
GET /v1/artworks?artist_id=123202 + (1.5 × 20)32
GET /v1/artworks?artist_id=1235002 + (1.5 × 500)752
GET /v1/artworks/456/similar3010 + (1.5 × 30)55
GET /v1/artists/123/related1510 + (1 × 15)25
POST /v1/artists/123/follow——0

Response headers

Every metered response includes the following headers. X-LiveArt-DataUnits is the authoritative cost of the call you just made:

HeaderExampleMeaning
X-LiveArt-DataUnits25.0DU cost of this specific call (a decimal number)
X-LiveArt-DataUnits-Remaining4975000Remaining DU balance in the current entitlement period
X-LiveArt-DataUnits-Period-End2026-12-31End date of the current entitlement period

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

Query parameters

ParameterDescription
fromStart date (ISO 8601). Defaults to the start of your current entitlement period.
toEnd date (ISO 8601). Defaults to today.
group_byOne of day, week, month, or endpoint. Optional — omitting returns the period total.

Response fields

  • Entitlement period — period_start / period_end, du_limit, du_consumed, du_remaining, and projected_eop (projected end-of-period consumption at the current run rate)
  • Daily and monthly windows — daily_du_* and monthly_du_* (limit / consumed / remaining each)
  • Separate API tank, on plans that include one — api_du_*, api_daily_du_*, and api_monthly_du_* mirror the three windows for API consumption. Requests made with an API key draw on this tank, and the X-LiveArt-DataUnits-* headers report its balance
  • breakdown[] — series of { label, pool, du_consumed, requests } when group_by is supplied. Each row belongs to one tank (pool is web or api); pass pool to receive one tank only. api_period_start and api_period_end give the API tank's own period

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 [email protected].

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.

GET/v1/artists
GET/v1/artists/stats
GET/v1/artists/{artist_id}
GET/v1/artists/{artist_id}/chart
GET/v1/artists/{artist_id}/related
GET/v1/artists/{artist_id}/events
GET/v1/artists/{artist_id}/sales-volume
GET/v1/artists/{artist_id}/sharpe-ratio
GET/v1/artists/{artist_id}/career-path-count
GET/v1/artists/{artist_id}/career-path-lae
GET/v1/artists/{artist_id}/returns-vs-period
GET/v1/artists/{artist_id}/compound-annual-returns
GET/v1/artists/followed
POST/v1/artists/{artist_id}/follow
DELETE/v1/artists/{artist_id}/follow

List artists

GET/v1/artists

Search, screen, and rank artists. Supports free-text search, a screener-grade range/facet filter grammar over the market metrics, and flexible sorting.

ParameterTypeDescription
limitinteger · ≤1000Page size. Default 100.
offsetinteger · ≥0Skip count.
qstringFree-text search across name and known synonyms. Without a sort parameter, matches come back largest catalog first (by artworks_count); with sort_by they follow that sort.
sort_by_total_sales · sort_by_market_capasc · descDeprecated. Use sort_by (TOTAL_SALES, MARKET_CAP) with sort_dir.
uid__instring[]Filter by artist UID — the uid field on each artist record (e.g. aMCprL).
id__ininteger[]Filter by numeric artist IDs.
is_topbooleanLimit to LiveArt's curated "top artist" set.
nationality__instring[]Filter by nationality — facet values come from /v1/artists/stats.
birth__gte / __lteintegerBound the artist's birth year.
is_livingbooleantrue = living artists only, false = deceased only.
market_cap · total_sales · max_price __gte / __ltenumberRange-filter the headline market metrics (USD). total_sales and max_price cover the trailing 12 months.
artworks_count · recent_lots_count __gte / __lteintegerRange-filter catalog depth and recent auction activity.
total_sales_lots_1yr · total_sales_price_median_1yr __gte / __ltenumberTrailing-12-month liquidity: lots sold and median price.
price_momentum_percentage_12mo · _5y __gte / __ltenumber12-month and 5-year price momentum (%).
followedbooleanOnly artists the authenticated user follows.
sort_bySortByEnumMARKET_CAP · TOTAL_SALES · MAX_PRICE · MEDIAN_1YR · RECENT_LOTS · LOTS_1YR · ARTWORKS · MOMENTUM_12MO · MOMENTUM_5Y · NAME · BIRTH
sort_dirasc · descDirection for sort_by. Defaults desc (NAME / BIRTH default asc).
include_chartbooleanInclude artist_index_chart per row (~480 points each — heavy). Default false.

Artist stats (filter facets)

GET/v1/artists/stats

Aggregate statistics over the filtered artist set — accepts the same filter grammar as /v1/artists and returns, per numeric field, a FieldStats object (min / max / p50 / p95) plus a nationalities facet with counts. Use it to seed range-slider bounds and nationality options in screener-style UIs.

Example: artists with a market cap of $100M or more

Request
GET /v1/artists/stats?market_cap__gte=100000000
200 OK · application/json (truncated)
{
  "market_cap":  { "min": 100147409.5442014, "max": 11265772458.130733, "p50": 218697986.79591703, "p95": 2482713206.940733 },
  "total_sales": { "min": 0, "max": 463124963, "p50": 7215987, "p95": 117735273.5 },
  "birth":       { "min": 1445, "max": 1984, "p50": 1902, "p95": 1959 },
  "nationalities": [
    { "value": "American", "count": 61 },
    { "value": "French",   "count": 47 },
    { "value": "Chinese",  "count": 22 }
  ]
}

Get a single artist

GET/v1/artists/{artist_id}

Returns the full ArtistSchema, including long biography, nationality, life dates, market metrics, and the artist's monthly index series: the bare values in artist_index_vector, and the same series with dates and lot counts in artist_index_chart.

200 OK · application/json (truncated)
{
  "id": 3505,
  "uid": "WH4QTN",
  "name": "Jean-Michel Basquiat",
  "nationality": "American",
  "birth": 1960,
  "death": 1988,
  "bio": "American painter and sculptor, 1960-1988",
  "total_sales": 141370311,
  "max_price": 52717500,
  "min_price": 367,
  "total_sales_lots_1yr": 34,
  "total_sales_price_median_1yr": 557697,
  "recent_lots_count": 42,
  "market_cap": 8617033331.444315,
  "price_momentum_percentage_12mo": 19.451214110101045,
  "price_momentum_percentage_5y": 14.673961050133633,
  "artworks_count": 1888,
  "is_followed": true,
  "photo_thumbnail_url": "https://images.liveart.ai/img/...?token=...&expiry=..."
}

Market metrics

These fields mean the same on every artist object, whichever endpoint returns it. All of the sales figures cover the trailing 12 months and count the buyer's premium.

FieldMeaning
total_salesAuction sales over the trailing 12 months: the sum of the premium-inclusive prices of the lots sold (USD).
max_price · min_priceHighest and lowest premium-inclusive price (USD) among the lots sold in the trailing 12 months.
total_sales_lots_1yrNumber of lots sold in the trailing 12 months.
total_sales_price_median_1yrMedian premium-inclusive price (USD) of the lots sold in the trailing 12 months.
recent_lots_countNumber of lots offered since 12 months ago, whatever the outcome: sold, passed, withdrawn, or still upcoming.
market_capMarket capitalization: the combined value, at today's LiveArt Estimates™, of all the artist's works that have ever sold at auction (USD).
price_momentum_percentage_12mo · _5yPrice momentum over 12 months and over 5 years, in percent.
artworks_countNumber of artwork records for the artist.

Artist price chart

GET/v1/artists/{artist_id}/chart

Monthly time series for an artist's market, as a TradingView-compatible ChartResponse. It carries the artist_index series (the artist's price index) and, where lot counts exist, a volume series (lots sold per month).

200 OK · application/json
{
  "resolution": "monthly",
  "unit": "index",
  "currency": "USD",
  "series": [
    {
      "id": "artist_index",
      "label": "Artist Index",
      "data": [
        { "time": "1986-02-01", "value": 50.3695, "value_low": null, "value_high": null },
        { "time": "1986-03-01", "value": 50.3305, "value_low": null, "value_high": null },
        { "time": "1986-04-01", "value": 50.2915, "value_low": null, "value_high": null }
      ]
    },
    {
      "id": "volume",
      "label": "Lots Sold",
      "data": [
        { "time": "1986-02-01", "value": 2, "value_low": null, "value_high": null },
        { "time": "1986-03-01", "value": 0, "value_low": null, "value_high": null },
        { "time": "1986-04-01", "value": 1, "value_low": null, "value_high": null }
      ]
    }
  ]
}

Related artists

GET/v1/artists/{artist_id}/related

Returns the artists LiveArt relates to this one, in ranked order, each as an artist object. Useful for "investors who tracked X also followed…" components.

Follow / unfollow

POST/v1/artists/{artist_id}/follow

Adds the artist to the authenticated user's follow list. Returns 204 No Content.

DELETE/v1/artists/{artist_id}/follow

Removes the artist from the follow list. Idempotent.

GET/v1/artists/followed

Paginated list of all artists the authenticated user follows.

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

GET/v1/artists/{artist_id}/events

Notable events in the artist's life and career. Events with a full date come first, oldest to newest, followed by events known only by year. Use the type filter to narrow to Life Events, Major Exhibitions, Major Publications, or Major Sales. Only visible events are returned.

Sales volume

GET/v1/artists/{artist_id}/sales-volume

Auction sales volume over time, broken down by outcome bucket. Each item represents a medium/category (e.g. Paintings, Prints) or the overall total (category_id = null). The dates array and the four count arrays — lots_above_estimate, lots_within_estimate, lots_below_estimate, and lots_not_sold — are aligned by index.

Sharpe ratio

GET/v1/artists/{artist_id}/sharpe-ratio

Risk-adjusted performance for the artist over 1, 2, 3, 5, 7, and 10-year horizons. A ratio above 1.0 is generally considered good; above 2.0 is excellent. Values may be null for periods with insufficient sales history.

Career path — by artwork count

GET/v1/artists/{artist_id}/career-path-count

Number of artworks per medium and creation year — a timeline of an artist's creative output. The year range is constrained by birth and death years where known. Useful for stacked bar/area charts of output volume across the career.

Career path — by LiveArt estimate

GET/v1/artists/{artist_id}/career-path-lae

Same shape as career-path-count but weighted by current LiveArt estimated value (USD) rather than artwork count — useful for visualizing the financial weight of each period in an artist's career.

Returns vs. holding period

GET/v1/artists/{artist_id}/returns-vs-period

Compound annual return (CAR) for every repeat-sale pair of the artist's artworks. Each data point is one resale event: car is the percentage annualized return (e.g. 12.5 = 12.5%/yr) and period_months is the months between the two auctions. Pairs with a holding period under 12 months are excluded.

Compound annual returns by year

GET/v1/artists/{artist_id}/compound-annual-returns

Median compound annual return across all of the artist's repeat sales, grouped by calendar year. car is expressed as a percentage (e.g. 8.7 = 8.7%/yr). Years with no repeat sales are omitted.

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.

GET/v1/artworks
POST/v1/artworks/search-by-image
GET/v1/artworks/recommended
GET/v1/artworks/{artwork_id}/chart
GET/v1/artworks/{artwork_id}/cagr
GET/v1/artworks/{artwork_id}/similar
GET/v1/artworks/{artwork_id}/editions
GET/v1/artworks/followed
POST/v1/artworks/{artwork_id}/follow
DELETE/v1/artworks/{artwork_id}/follow
POST/v1/artworks/share
GET/v1/artworks/shared/{token}

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

ParameterTypeDescription
uid · uid__instring · string[]Look up specific artworks by UID — the uid field on each artwork record (e.g. TfCwLg).
id · id__ininteger · integer[]Look up specific artworks by numeric id.
artist_id · artist_id__ininteger · integer[]Restrict to one or more artists.
category_id · category_id__ininteger · integer[]Painting, sculpture, photography, etc. (see categories).
creation_year__gte / __lteintegerBound the year of creation.
size__insmall · medium · big · otherLiveArt's normalized size buckets.
measurements_*_cm__gte / __ltenumberNumeric bounds for height, width, depth (cm).
materials · materials__instring · string[]Exact match on the artwork's full materials text (for example "oil on canvas").
searchstringFull-text search over the artwork's title and catalogue text.
last_lot_statusunknown · upcoming · withdrawn · sold · passedMost recent lot outcome for this artwork.
date_last_sold__gte / __ltedateBound by date of last completed sale.
date_last_upcoming__gte / __ltedateBound by upcoming sale date.
current_estimated_price__gte / __ltenumberBound by LiveArt Estimate™ value (USD).
price_momentum_12mo__gte / __ltenumber12-month change in the LiveArt Estimate™, as a fraction (0.124 = +12.4%).
last_hammer_price_usd__gte / __lteintegerMost recent hammer price in USD.
last_premium_price_usd__gte / __lteintegerMost recent premium-inclusive price (USD).
without_editionsbooleanExclude editioned multiples — show only unique works.
with_imagesbooleanRestrict to artworks with at least one image. Default false.
sale_auction_house_id · sale_auction_house_id__ininteger · integer[]Works that have appeared in a sale at these auction houses.
sale_start_datetime__gte / __ltedatetimeWorks offered in a sale that started within this window.
market_cap__gtenumberMinimum artist market cap (filter out micro-cap artists).
preferred_currencyenumConvert prices to one of 16 supported currencies.
sortArtworkSortEnumSee Sorting.
sort_by_priceasc · descSort by the most recent sale price, premium included (USD).

Example: Basquiat works estimated $1M–$5M that sold since 2020, most recent first

curl "https://api.liveart.ai/v1/artworks?\
artist_id=3505&\
last_lot_status=sold&\
current_estimated_price__gte=1000000&\
current_estimated_price__lte=5000000&\
date_last_sold__gte=2020-01-01&\
sort=SALE_DATE_DESC&\
with_images=true" \
  -H "Authorization: Bearer $LIVEART_API_KEY"

Response shape

200 OK · application/json
{
  "items": [
    {
      "id": 9012345,
      "uid": "Zr8TqL",
      "slug": "untitled-1982",
      "last_lot_status": "sold",
      "date_last_sold": "2025-05-15",
      "currency": "USD",
      "current_estimated_price": 3847215.44,
      "current_estimated_price_min": 3400000,
      "current_estimated_price_max": 4300000,
      "price_momentum_12mo": 0.12384150293841,
      "price_change_12mo": 423943.1815065753,
      "description": { "name": "Untitled", "materials": "acrylic and oilstick on canvas", "creation_year": 1982 },
      "price": { "currency": "USD", "hammer_usd": 3200000, "premium_usd": 3920000, "hammer_estimate_min_usd": 2500000, "hammer_estimate_max_usd": 3500000 }
    }
  ],
  "total_count": 60,
  "limit": 20,
  "offset": 0
}
Working with images

Artwork and lot records carry an image object (on artworks, under description.image). Its urls map holds five renditions of the work, keyed by width: w240, w480, w768, w1200, and w1920. Each one is the complete work at its true aspect ratio — never cropped, never enlarged. Pick the smallest rendition that covers your display size.

The URLs are signed and time-limited. Use each one exactly as returned: changing the width, the path, or any other part invalidates the signature and the request returns 403. Every URL stops working at its expiry (a Unix timestamp, at most a few days ahead). Do not store these URLs; request the record again when you need the image.

Requests without an API key receive blurred previews. The legacy fields large_url, medium_url, and thumbnail_url are retired and return null. Images are provided for reference; see Image rights.

Image object
"image": {
  "id": 134321261,
  "urls": {
    "w240":  "https://images.liveart.ai/img/width=240,fit=scale-down,quality=72,format=auto/lots/8147201/a13ac2b0...?token=...&expiry=1790812800",
    "w480":  "https://images.liveart.ai/img/width=480,...",
    "w768":  "https://images.liveart.ai/img/width=768,...",
    "w1200": "https://images.liveart.ai/img/width=1200,...",
    "w1920": "https://images.liveart.ai/img/width=1920,..."
  },
  "large_url": null,
  "medium_url": null,
  "thumbnail_url": null
}

Artwork price chart

GET/v1/artworks/{artwork_id}/chart

Returns a ChartResponse for the individual artwork: the LiveArt Estimate™ for the work as a monthly series in USD (series price_prediction). Each point carries the estimate in value and its confidence band in value_low and value_high. Returns 404 if the artwork has no estimate series.

Similar artworks

GET/v1/artworks/{artwork_id}/similar

Vector-similarity search across the catalog: returns artworks comparable in artist, period, medium, scale, and market segment. Optional preferred_currency for price normalization.

Editions

GET/v1/artworks/{artwork_id}/editions

For editioned works (prints, photographs, multiples), returns every edition LiveArt has tracked, with the full lot history of each. Useful for building edition-level price ladders.

CAGR

GET/v1/artworks/{artwork_id}/cagr

Compound Annual Growth Rate of the artwork's LiveArt Estimate™ series — the smoothed yearly growth from the first point of the series to the latest. A value of 0.12 means 12% per year. Returns 404 if the artwork has no estimate series.

Recommended artworks

GET/v1/artworks/recommended

Personalized artwork recommendations for the authenticated user. Sourced from two signals: artworks similar to ones the user already follows (via pre-computed similarity scores), plus recent works by artists the user follows. Already-followed artworks are excluded from the result set.

Search by image

POST/v1/artworks/search-by-image

Reverse image search across the catalog: returns visually similar artworks ranked by score (descending). Provide exactly one anchor — a multipart/form-data image file, a public image_url, or a collectable_id to anchor on one of your own collectables' images. Everything other than the image file is sent as a query parameter.

ParameterTypeDescription
imagefile (multipart)The query image, uploaded directly.
image_urlstringPublicly fetchable image URL, as an alternative to uploading.
collectable_idintegerAnchor on a stored collectable's image (owner-scoped).
min_scorenumberDrop results below this similarity score.
exclude_artwork_id__ininteger[]Exclude specific artworks from the results.
limitinteger · ≤200Result count. Default 50.
…pool filtersquery paramsA subset of the /v1/artworks filters narrows the candidate pool without changing score order: artist_id, artist_id__in, category_id__in, materials__in, size__in, and the __gte / __lte bounds on current_estimated_price, last_hammer_price_usd, creation_year, and the three measurements_*_cm fields.
cURL
# Find visually similar paintings, anchored on an uploaded photo
curl -X POST "https://api.liveart.ai/v1/artworks/search-by-image?\
category_id__in=1&\
current_estimated_price__lte=5000000&\
min_score=0.5&\
limit=20" \
  -H "Authorization: Bearer $LIVEART_API_KEY" \
  -F "image=@/path/to/photo.jpg"
200 OK · application/json (truncated)
{
  "results": [
    {
      "score": 0.94,
      "artwork": {
        "id": 9012345,
        "uid": "Zr8TqL",
        "current_estimated_price": 3847215.44
      }
    },
    { "score": 0.86, "artwork": { "id": 8120442, "uid": "aB3xK9" } }
  ]
}

Follow / unfollow

POST/v1/artworks/{artwork_id}/follow

Adds the artwork to the authenticated user's follow list. Returns 204 No Content.

DELETE/v1/artworks/{artwork_id}/follow

Removes the artwork from the follow list. Idempotent.

GET/v1/artworks/followed

Paginated list of artworks the authenticated user follows.

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.

GET/v1/lots
GET/v1/lots/followed
POST/v1/lots/{lot_id}/follow
DELETE/v1/lots/{lot_id}/follow
POST/v1/lots/share
GET/v1/lots/shared/{token}

List lots

ParameterTypeDescription
id · id__ininteger · integer[]Look up specific lots by numeric ID.
status · status__inunknown · upcoming · withdrawn · sold · passedLot lifecycle state.
sale_status · sale_status__inclosed · upcoming · live · session_offState of the parent sale.
auction_house_id · sale_auction_house_idintegerFilter by auction house at the lot or sale level.
sale_id · sale_id__ininteger · integer[]Restrict to specific sales.
sale_location · sale_location__instring · string[]Filter by sale location string (e.g. "New York", "London").
sale_datetime__gte / __ltedatetimeBound by sale time.
hammer_price_usd__gte / __lteintegerBound by realized hammer price (USD).
hammer_price_estimate_max_usd__gte / __lteintegerBound by high estimate (USD).
premium_price_usd__gte / __lteintegerBound by premium-inclusive price (USD).
artist_id · artist_uid · artwork_id · artwork_uidinteger · stringFilter by artist or artwork. The UID forms also take a list: artist_uid__in, artwork_uid__in.
is_topbooleanCurated "headline" lots only.
searchstringFull-text search over the lot's artwork: title and catalogue text.
sortLotSortEnumSee Sorting.
preferred_currencyenumConvert all monetary fields.

Lot object (excerpt)

Each entry in items is a lot object like the one below. To fetch specific lots, pass their IDs in id__in.

Lot object
{
  "id": 81472019,
  "lot_num": "24A",
  "status": "sold",
  "auction_house_id": 1,
  "auction_house_name": "Sotheby's",
  "sale_id": 90217,
  "is_top": true,
  "house_guaranteed_mark": true,
  "third_party_mark": true,
  "reserve_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" }
}

Guarantee and reserve marks

Three booleans carry the marks the auction house prints for the lot in its catalogue. They are returned to signed-in members and API keys. false means the house did not mark the lot or the lot has not been checked: coverage differs by house and by date, so don’t read a false as “no guarantee”.

FieldTypeMeaning
house_guaranteed_markbooleanThe house marks the lot as guaranteed: the seller is promised a minimum price. Also set when the house doesn't say who guarantees it.
third_party_markbooleanA third party guarantees the lot or has placed an irrevocable bid on it. A guarantee the house shares with a third party sets both fields.
reserve_markbooleantrue means no reserve: the lot is offered without a minimum price and sells to the highest bid. It never means the lot has a reserve.

Follow lots

POST/v1/lots/{lot_id}/follow

Track an upcoming lot. Combine with /v1/lots/followed to power a personalized watchlist.

DELETE/v1/lots/{lot_id}/follow

Remove a lot from the watchlist. Idempotent.

GET/v1/lots/followed

Same query grammar as /v1/lots, scoped to the user's followed 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.

GET/v1/sales
GET/v1/sales/followed
POST/v1/sales/{sale_id}/follow
DELETE/v1/sales/{sale_id}/follow

List sales

ParameterTypeDescription
id · id__ininteger · integer[]Look up specific sales by numeric ID.
auction_house_id · auction_house_id__ininteger · integer[]Filter by auction house.
name__ilikestringSubstring search on sale name.
status · status__inclosed · upcoming · live · session_offLifecycle state.
is_onlinebooleanFilter online-only or in-room sales.
is_bids_streamingbooleanSales whose live bid stream is wired into LiveArt's feed.
location · location__in · location_id · location_id__instring / integerFilter by city/region.
start_datetime__gte / __ltedatetimeBound the sale start.
end_datetime__gte / __ltedatetimeBound the sale end.
sortSaleSortEnumSee Sorting.
preferred_currencystringCurrency for the *_preferred aggregate fields.

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 collectable is 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, private sale history, and comp set. Every collectable is scoped to the authenticated user; there is no public variant.

Authentication

All collectable endpoints require a bearer token and operate only on the calling user's own records. The X-LiveArt-DataUnits header on each response gives the cost of the call — see Data Units.

GET/v1/collectables
POST/v1/collectables
GET/v1/collectables/{collectable_id}
PATCH/v1/collectables/{collectable_id}
DELETE/v1/collectables/{collectable_id}
POST/v1/collectables/{collectable_id}/image
GET/v1/collectables/{collectable_id}/acquired
PATCH/v1/collectables/{collectable_id}/acquired
GET/v1/collectables/{collectable_id}/appraisals
POST/v1/collectables/{collectable_id}/appraisals
PATCH/v1/collectables/{collectable_id}/appraisals/{appraisal_id}
DELETE/v1/collectables/{collectable_id}/appraisals/{appraisal_id}
GET/v1/collectables/{collectable_id}/provenance
POST/v1/collectables/{collectable_id}/provenance
PATCH/v1/collectables/{collectable_id}/provenance/{provenance_id}
DELETE/v1/collectables/{collectable_id}/provenance/{provenance_id}
GET/v1/collectables/{collectable_id}/sales
POST/v1/collectables/{collectable_id}/sales
PATCH/v1/collectables/{collectable_id}/sales/{sale_id}
DELETE/v1/collectables/{collectable_id}/sales/{sale_id}
GET/v1/collectables/{collectable_id}/comps
PUT/v1/collectables/{collectable_id}/comps
DELETE/v1/collectables/{collectable_id}/comps

List & create collectables

GET/v1/collectables

Returns the authenticated user's collection as a paginated CollectablesListResponse (items, total_count, limit, offset). Each item is a CollectableSchema with the LiveArt machine estimate, optional manual valuation, momentum, and physical attributes.

POST/v1/collectables

Create a collectable. Body is multipart/form-data (so an image can be attached at creation): artist_id, category_id, edition_unique_type, optional suggested_artwork_id (to seed from a known LiveArt artwork), and an optional image file. Returns the created CollectableSchema. Refine the remaining fields afterward with PATCH.

cURL
# multipart/form-data — image optional
curl -X POST https://api.liveart.ai/v1/collectables \
  -H "Authorization: Bearer $LIVEART_API_KEY" \
  -F "artist_id=3505" \
  -F "category_id=1" \
  -F "edition_unique_type=unique" \
  -F "image=@/path/to/work.jpg"
201 Created · application/json
{
  "id": 4821,
  "uid": "8f3a2b1d-6c4e-4f7a-9b2d-5e1c7a3f9d04",
  "title": "Untitled (Skull)",
  "artist_id": 3505,
  "artist_name": "Jean-Michel Basquiat",
  "category_id": 1,
  "category_name": "paintings",
  "creation_year": 1982,
  "current_estimated_price": 3850000,
  "machine_estimated_price": 3720000,
  "manual_price_value": null,
  "selected_price_type": null,
  "price_momentum_12mo": 0.124,
  "condition": "good",
  "signature": true,
  "measurements_unit": "cm",
  "measurements_height": 183,
  "measurements_width": 173,
  "material_ids": [28, 2163],
  "substrate_ids": [237],
  "current_location": "New York, NY",
  "image_thumbnail_url": "https://images.liveart.ai/img/...?token=...&expiry=..."
}

Get, update & delete

GET/v1/collectables/{collectable_id}

Full CollectableSchema for a single record.

PATCH/v1/collectables/{collectable_id}

Partial update via CollectableUpdateInput. Every field is optional — send only what changed (title, valuation choice via selected_price_type / manual_price_value, condition, measurements, edition data, and the material_ids / substrate_ids / surface_ids / damage_ids arrays, which reference the reference-data tables).

DELETE/v1/collectables/{collectable_id}

Permanently removes the collectable and its child records (appraisals, provenance, sales).

Image

POST/v1/collectables/{collectable_id}/image

Upload or replace the collectable's image. multipart/form-data with a single image file part. Returns the updated record with fresh image_url / image_thumbnail_url.

Acquisition details

GET/v1/collectables/{collectable_id}/acquired

How and when the work was acquired — an AcquiredSchema (date, price + currency, location, source type and seller/dealer/auction-house name). When use_instead_of_estimates is set, the acquisition price anchors the collectable's value instead of the machine estimate.

PATCH/v1/collectables/{collectable_id}/acquired

Update acquisition details via AcquiredUpdateInput (partial).

Appraisals

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

GET/v1/collectables/{collectable_id}/appraisals

List all appraisals for the collectable.

POST/v1/collectables/{collectable_id}/appraisals

Add an appraisal (AppraisalCreateInput).

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

Update an appraisal (partial).

DELETE/v1/collectables/{collectable_id}/appraisals/{appraisal_id}

Remove an appraisal.

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).

GET/v1/collectables/{collectable_id}/provenance

List provenance records.

POST/v1/collectables/{collectable_id}/provenance

Add a provenance record (ProvenanceCreateInput).

PATCH/v1/collectables/{collectable_id}/provenance/{provenance_id}

Update a provenance record (partial).

DELETE/v1/collectables/{collectable_id}/provenance/{provenance_id}

Remove a provenance record.

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.

GET/v1/collectables/{collectable_id}/sales

List the collectable's sale records.

POST/v1/collectables/{collectable_id}/sales

Record a sale (CollectableSaleCreateInput).

PATCH/v1/collectables/{collectable_id}/sales/{sale_id}

Update a sale record (partial).

DELETE/v1/collectables/{collectable_id}/sales/{sale_id}

Remove a sale record.

Comp set

A curated set of comparable artworks used to benchmark the collectable's valuation. Each comp references a LiveArt artwork (artist_id + artwork_id) with an optional weight (default 1.0); responses resolve display names and carry similarity and verified flags.

GET/v1/collectables/{collectable_id}/comps

Returns the saved comp set. Always 200 — an empty set ({ "collectable_id": 4821, "comps": [], "updated_at": null }) when none is saved.

PUT/v1/collectables/{collectable_id}/comps

Full-replace semantics: send the complete set every time; the server replaces whatever was stored and returns the persisted set with resolved names. An empty comps array clears the set.

PUT body
PUT /v1/collectables/4821/comps
{
  "comps": [
    { "artist_id": 3505, "artwork_id": 9012345, "weight": 1.0 },
    { "artist_id": 3505, "artwork_id": 8120442, "weight": 0.5 }
  ]
}
DELETE/v1/collectables/{collectable_id}/comps

Clears the comp set — equivalent to PUT with an empty array.

Auction Houses

GET/v1/auction-houses

Returns the canonical list of auction houses LiveArt indexes. Use the integer id for filtering anywhere in the API. Optional name query parameter for substring search.

200 OK · application/json
[
  { "id": 4, "name": "Christie's", "slug": "Christies", "priority_order": 0, "is_live": true },
  { "id": 1, "name": "Sotheby's",  "slug": "Sothebys",  "priority_order": 1, "is_live": true },
  { "id": 5, "name": "Phillips",   "slug": "Phillips",  "priority_order": 2, "is_live": true }
]

Auction Locations

GET/v1/auction-locations

Returns every known auction sale location (city/venue). Pass an optional name query parameter for substring/autocomplete search. The name value, exactly as returned, can be passed to the sale_location (or sale_location__in) filter on /v1/artworks and /v1/lots, and to the location (or location__in) filter on /v1/sales. The id works with location_id on /v1/sales.

Categories

GET/v1/categories

The canonical taxonomy used to classify every artwork. Use category id values with category_id__in on artwork and lot endpoints.

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.

GET/v1/materials
GET/v1/substrates
GET/v1/surfaces
GET/v1/damages
GET/v1/plans
GET/v1/materials

Media an artwork can be made of (oil, acrylic, bronze, …). Use the id values in material_ids when creating/updating a collectable.

200 OK · application/json
[
  { "id": 418,  "name": "bronze", "label": "bronze" },
  { "id": 495,  "name": "canvas", "label": "canvas" },
  { "id": 2130, "name": "oil",    "label": "oil" }
]
GET/v1/substrates

Support surfaces a work is executed on (canvas, paper, panel, …) — feeds substrate_ids.

GET/v1/surfaces

Surface treatments/finishes — feeds surface_ids.

GET/v1/damages

Condition/damage descriptors used in appraisals and condition reports — feeds damage_ids. (Same { id, name, label } shape as the others.)

Plans

GET/v1/plans

The catalog of plan tiers, app and API, as PlanSchema objects: slug, display_name, du_limit (Data Units per period_days), rps_limit / rpm_limit, throttle_multiplier, sort_order, and a features blob. Drives plan-comparison UI without hard-coding limits client-side.

Market

GET/v1/market/index-chart

The global LiveArt Art Index as a time series, optionally overlaid with one or more traditional financial benchmarks for comparison. Returns a GlobalArtIndexChartResponse with art_data (the art index points, each a date and an index value) and finance_data (one series per requested benchmark, identified by its quote).

Query parameters

ParameterTypeDescription
financeFinanceQuote[]Benchmarks to overlay (repeat the param). One or more of SNP500, GOLD, DOW_JONES, MSCI_WORLD_REAL_ESTATE, BITCOIN_USD. Omit for the art index alone.
200 OK · application/json
{
  "art_data": [
    { "date": "1986-01-01", "index": 1 },
    { "date": "1986-02-01", "index": 0.9996543009677532 },
    { "date": "1986-03-01", "index": 0.9971815986270011 }
  ],
  "finance_data": [
    {
      "quote": "SNP500",
      "data": [
        { "date": "1985-01-01", "index": 1 },
        { "date": "1985-02-01", "index": 1.0086287799968605 }
      ]
    }
  ]
}

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.

POST/v1/artworks/share

Body: { "artwork_ids": [int], "currency": "USD" }. Returns { "token": "abc123…" }.

GET/v1/artworks/shared/{token}

Public — no auth required. Returns the same ArtworksResponse as /v1/artworks.

POST/v1/lots/share

Body: { "lot_ids": [int], "currency": "USD" }. Returns a token.

GET/v1/lots/shared/{token}

Public — no auth required.

Health check

GET/healthcheck

Public, unauthenticated endpoint that returns 200 OK when the API is reachable. Suitable for uptime monitors and deployment smoke tests.

Schemas

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

SchemaReturned byDescription
ArtistSchemaartist endpointsBiographical and market-level data on an artist.
ArtworkSchema/v1/artworks, /v1/artworks/{id}/similarUnique artwork with current estimate, momentum, and embedded DescriptionSchema + PriceSchema.
LotSchema/v1/lots, /v1/lots/followedA single auction-house offering with embedded artwork, sale, image, and price.
SaleSchema/v1/sales, /v1/sales/followedAn auction session with aggregate totals and sell-through breakdown.
PriceSchemaartworks, lotsNative + USD + preferred-currency price triples.
ChartResponseartist + artwork chart endpointsTradingView-compatible time-series with one or more ChartSeries.
CategorySchema · AuctionHouseSchemareference endpointsLookup tables.
EditionsResponse · EditionSchema/v1/artworks/{id}/editionsEdition ladder for multiples.
ArtistStatsResponse · FieldStats/v1/artists/statsPer-field min / max / p50 / p95 aggregates + nationality facets over the filtered artist set.
SearchByImageResponse · ImageSearchResult/v1/artworks/search-by-image{ score, artwork } pairs ranked by visual similarity.
CollectableSchema/v1/collectablesA work in a user's collection. Its acquisition details, appraisals, provenance, and sale records are separate sub-resources.
AppraisalSchema · ProvenanceSchema · CollectableSaleSchema · AcquiredSchemacollectable sub-resourcesValuation history, ownership chain, private sales, and acquisition details.
CompSetSchema · Comp/v1/collectables/{id}/compsPersisted comparable-artwork set with weights, similarity, and verification flags.
MaterialSchema · PlanSchemareference-data endpoints{ id, name, label } vocabularies (materials/substrates/surfaces/damages) and the plan catalog.
ArtistPublicSchema · ArtworksPublicResponse · LotsPublicResponse · SalesPublicResponseunauthenticated list callsReduced variants returned to requests without a key (see Authentication).

Field-level definitions for every schema are in the OpenAPI spec. Look them up there by the short names used on this page: a few component names carry a module prefix, such as core__artists__schema__ArtistSchema.

OpenAPI specification

The full machine-readable specification is published at:

URL
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

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

Generate TypeScript types

shell
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.

DateChange
2026-10-28Disabled accounts. An account that has been disabled answers 403 on every endpoint, for its API keys and its sessions alike, with "code": "account_disabled" at the top level of the body. Branch on the code, not the status alone: other refusals answer 403 too.
2026-10-15Momentum units documented and the trial source. Every rate field now states its unit: an artwork's price_momentum_12mo and price_momentum_24mo, their __gte / __lte filters and cagr are fractions (0.12 = 12%); an artist's price_momentum_percentage_12mo and price_momentum_percentage_5y, their filters and /v1/artists/stats are percent (12 = 12%). price_change_12mo and price_change_24mo (and their *_usd variants) are null for an artwork without a LiveArt Estimate™, where they used to be 0. Artwork responses carry the artist's momentum as description.artist.price_momentum_percentage_12mo. A collection holding linked to an artwork reports that artwork's price_momentum_*. An artist momentum of exactly zero is returned as 0 instead of null. POST /v1/builder/trial accepts an optional source, and the OpenAPI document's description says how to get a key.
2026-10-13Stricter requests and consistent errors. Three changes can affect an existing integration: a query parameter an endpoint does not define now returns 422 where it used to be ignored; a rejected key returns 401 on every endpoint, and 403 now means the key was accepted but access is not allowed; NOK is no longer a preferred_currency (SEK and ZAR are new). Also: an explicit sort now applies to /v1/artists searches with q; date-time filters accept Z and UTC offsets; numeric and enum __in filters accept comma-separated values; /v1/artworks gains id and id__in and filters on without_editions again; LiveArt Estimate™ fields gain *_usd and *_preferred variants, and money values are rounded to two decimals; /v1/usage splits breakdown[] by pool; a request for the chart or the similar works of an unknown artwork returns 404.
2026-07-23/v1/usage response expanded with daily and monthly consumption windows plus a separate API Data-Unit tank (daily_du_*, monthly_du_*, api_*) alongside the entitlement-period totals.
2026-07-18Search-by-image extended: collectable_id anchor, the /v1/artworks filter vocabulary on the candidate pool, min_score, and exclude_artwork_id__in.
2026-07-15Added collectable comp sets — GET/PUT/DELETE /v1/collectables/{id}/comps with full-replace PUT semantics.
2026-06-22Artist screener support: range and facet filters on /v1/artists (market metrics, birth, nationality__in, is_living), the new price_momentum_percentage_5y metric, generic sort_by / sort_dir, include_chart, and the /v1/artists/stats facet endpoint. New lot sort values RAW_LOT_ID_ASC/DESC.
2026-06-15Added POST /v1/artworks/search-by-image — reverse image search returning score-ranked matches (image upload or image_url).
2026-05-28Added the Collectables API — read-write personal-collection records (/v1/collectables) with image upload, acquisition details, appraisals, provenance, and private sale history.
2026-05-14Added reference-data vocabularies (/v1/materials, /v1/substrates, /v1/surfaces, /v1/damages), /v1/plans, and the global art-vs- finance index endpoint /v1/market/index-chart.
2026-05-02List endpoints now return reduced *Public schemas to requests without a key; each 200 is modeled as an anyOf of the full and public schema.
2026-04-30Added artist analytics suite (/v1/artists/{id}/sales-volume, /sharpe-ratio, /career-path-count, /career-path-lae, /returns-vs-period, /compound-annual-returns, /events), artwork CAGR (/v1/artworks/{id}/cagr), artwork follow + recommendations (/v1/artworks/{id}/follow, /v1/artworks/followed, /v1/artworks/recommended), and reference endpoints /v1/auction-locations and /v1/currencies.
2026-04-22Introduced Data Units (DU) metering. Added /v1/usage endpoint and X-LiveArt-DataUnits* response headers.
2026-04-01Added preferred_currency to sale list endpoints.
2026-02-12Added price_momentum_24mo and price_change_24mo on ArtworkSchema.
2025-12-04Added /v1/artworks/{id}/editions.
2025-10-22Added bulk lookup filters: id__in on artists, lots, and sales; uid__in on artists and artworks.
2025-09-01Initial public release of /v1.

Need help?

Email [email protected] for support, enterprise pricing, or questions about embedding LiveArt data in production systems.