REST API
Valuation API
Plug the ARST valuator into your workflow with one HTTP call. API-key authentication, JSON responses, no proprietary SDK. You pay per valuation with one-off token packs — there is no subscription.
Start in 5 minutes
From zero to your first valuation. The first four steps do not cost a single token.
- 01
Create your account
Free sign-up, two fields. You get 5 welcome credits to try the engine on real data.
- 02
Verify your email
You receive a verification link valid for 24 hours. It is mandatory: you cannot sign in until the address is verified.
- 03
Create a sandbox key
In My account → API Keys, tick the Sandbox box and create. The key starts with sk_test_ and its plaintext value is shown ONCE: copy it right there.
- 04
Make your first call
Paste the curl on the right with your key. Sandbox returns real engine valuations and never touches your balance (cap: 1,000 calls per day).
- 05
Go live
Create a second key with the Sandbox box unticked: it starts with sk_live_ and every valuation costs 1 token. Same code — only the key changes.
Your first request
curl -X POST 'https://rv.arstdata.com/api/v1/valuation' \
-H 'Authorization: Bearer sk_test_TU_CLAVE' \
-H 'Content-Type: application/json' \
-d '{
"country": "ES",
"brand": "BMW",
"model": "320D",
"year": 2020,
"km": 65000,
"fuel": "diesel",
"current_price": 25000,
"version": "320d xDrive M Sport",
"power_cv": 190,
"transmission": "automatic"
}'Response (abridged)
{
"country": "ES",
"brand": "BMW",
"model": "320D",
"year": 2020,
"km": 65000,
"fuel": "diesel",
"currency": "EUR",
"p10": 22500,
"p50": 26800,
"p90": 31200,
"confidence": "high",
"sample_size": 847,
"model_recognized": true,
"rv_conservative": 21900,
"horizons": {
"0": { "price": 26800, "price_low": 22500, "price_high": 31200,
"pct": 59.4, "pct_low": 49.9, "pct_high": 69.2 },
"12": { "price": 25100, "price_low": 21100, "price_high": 29200,
"pct": 55.6, "pct_low": 46.8, "pct_high": 64.7 },
"72": { "price": 14200, "price_low": 11900, "price_high": 16500,
"pct": 31.5, "pct_low": 26.4, "pct_high": 36.6 }
},
"tokens_remaining": 5
}The full response carries all 13 horizons: 0 (today) and then every 6 months up to 72. Each horizon includes the median price, the P10/P90 band, and the same three figures as a percentage of the new price.
The only difference between sandbox and production is the value of the Authorization header. The URL, the body and the response shape are identical.
Authentication
Every endpoint except the service status requires an API key in the Authorization header. There is no query parameter and no key in the URL.
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Production key
sk_live_ prefix — spends tokens from your balance.
Sandbox key
sk_test_ prefix — real data, never spends tokens. Capped at 1,000 calls per day, reset at 00:00 UTC.
Format
Bearer token. Up to 10 active keys per account; revoking one leaves the others untouched.
Alternative
Web session (arst_token cookie) for browser calls made with your account already signed in.
Create and revoke keys in My account → API Keys. We store only a hash: if you lose the plaintext value you must create a new key.
How billing works
No subscription, no monthly fee, no lock-in. You buy a token pack when you need it, and that balance does not expire just because a month went by.
Token packs · one-off purchase
5 tokens
14.99 € incl. VAT
3 €/token
15 tokens
39.99 € incl. VAT
2.67 €/token
40 tokens
95.99 € incl. VAT
2.40 €/token
100 tokens
216.99 € incl. VAT
2.17 €/token
Business prices, excluding VAT. For individuals, below, with 21% VAT included. Tokens are added to whatever balance you already have.
See packs and buy
Token packs · one-off purchase
Pacing limits
| Endpoints | Per minute | Per day |
|---|---|---|
/valuation · /comparable | 60 | uncapped |
/batch · /batch/async | 12 | uncapped |
/pdf | 10 | 300 |
/pvpr · /catalog/* · /market-index | 600 | 10,000 |
/usage · /batch/async/{job_id} | 120 | 5,000 |
Per key, across keyed routes | 300 | uncapped |
Sandbox key (sk_test_) | same | 1,000 |
These are operational limits, identical for everyone: they protect the service from runaway loops, they are not a product tier. They apply BEFORE your balance is touched, so a throttled request never costs a token. Every 429 carries a Retry-After header, and daily caps reset at 00:00 UTC.
Endpoints
Thirteen routes in production. The rule never changes: valuing costs tokens, looking things up does not.
| Method | Endpoint | Tokens | What it does |
|---|---|---|---|
| POST | /valuation | 1 | Value one vehicle: price band today plus a 72-month projection. |
| POST | /batch | 1 / vehicle | Value up to 50 vehicles in a single synchronous call. |
| POST | /batch/async | 1 / vehicle | Queue a batch and get a job identifier back. |
| POST | /comparable | 1 | Vehicles comparable to yours in the current market. |
| GET | /batch/async/{job_id} | 0 | Poll the status and result of a queued batch. |
| POST | /pdf | 0 | Turn an already-computed valuation into a PDF report. |
| GET | /pvpr | 0 | Recommended new-vehicle price for a brand/model/year. |
| GET | /catalog/brands | 0 | Brands with live supply in a country, ordered by volume. |
| GET | /catalog/models | 0 | Models of a brand in a country, ordered by volume. |
| GET | /catalog/versions | 0 | Trims of a model with new price and the years covered. |
| GET | /market-index | 0 | Monthly used-car market index, per country. |
| GET | /usage | 0 | Your token balance and your usage per endpoint class. |
| GET | /healthNo key | 0 | Service and per-country status. No authentication. |
| GET | /countriesNo key | 0 | Available markets and their model status. No authentication. |
Request details
Body, parameters and real response for each endpoint. Expand the one you need.
Common errors
Every error returns JSON with a detail field. The first three are the ones you will meet while integrating.
| HTTP | What happened and how to fix it |
|---|---|
401 | The Authorization header is missing, or the key is invalid, revoked, or in a shape we do not recognise. Check that you send "Bearer " in front of the key. |
402 | Balance exhausted: the call needs more tokens than you have left. The detail states how many are needed and how many remain. Buy a pack and the very same request works, unchanged. |
422 | Invalid parameters. The most common one while integrating is forgetting current_price, which is mandatory; you also get it for a country or fuel outside the supported list, or a brand/model combination that does not exist in that market. The detail points at the exact field. |
429 | You exceeded the pacing or the daily cap for that endpoint class. Wait the number of seconds in the Retry-After header and retry: no token was charged. |
413 | Body too large (PDF generation only). Send the valuation JSON as-is, without attaching anything else. |
503 | That country has no model available right now, or the service is reloading artifacts. It is temporary: retry in a few minutes. |
Quick example
curl -X POST 'https://rv.arstdata.com/api/v1/valuation' \
-H 'Authorization: Bearer sk_test_TU_CLAVE' \
-H 'Content-Type: application/json' \
-d '{
"country": "ES",
"brand": "BMW",
"model": "320D",
"year": 2020,
"km": 65000,
"fuel": "diesel",
"current_price": 25000,
"version": "320d xDrive M Sport",
"power_cv": 190,
"transmission": "automatic"
}'At a glance
Create an API key
My account → API Keys → Sandbox box
Buy tokens
One-off packs, no subscription