API Documentation

Getting Started

1. Request access from Settings > API Access.
2. A verified seller is approved instantly; otherwise we'll review your request shortly.
3. Once approved, generate your token -- it's shown exactly once, so copy it somewhere safe.
4. Include it as a Bearer token on every request to the endpoints below.

Authentication

Every request (except the public reference endpoints) must include your token in the Authorization header:

Authorization: Bearer osk_your_token_here

Tokens are tied to your account -- every listing you create, edit, or read through the API is scoped to your own inventory only.

Listing Lifecycle

A listing created through the API always starts as a draft, the same as starting one by hand on the site -- it can't publish without at least one photo, and this call can't carry one.

1. POST a new listing -- it's created as a draft.
2. Upload one or more photos to it.
3. POST a status change (e.g. "AV") to publish it.

The account your token belongs to

curl https://onlysalvage.com/api/v1/me/ \
  -H "Authorization: Bearer osk_your_token_here"

Valid values for status, vehicle_type, fuel_type, etc.

curl https://onlysalvage.com/api/v1/schema/choices/

Every option a listing can be marked with -- read the ids, then send them as "options" when you create or update a listing (no token required)

curl https://onlysalvage.com/api/v1/options/

List all vehicle makes (no token required)

curl https://onlysalvage.com/api/inventory/makes/

List models for a given make (no token required)

curl "https://onlysalvage.com/api/inventory/models/?make=21"

List your own listings -- filterable, see below

curl "https://onlysalvage.com/api/v1/listings/?status=AV&min_price=5000" \
  -H "Authorization: Bearer osk_your_token_here"

Create a new listing (always starts as a draft)

curl -X POST https://onlysalvage.com/api/v1/listings/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "vin": "1HGCM82633A004352",
    "year": 2018,
    "make": 21,
    "model": 186,
    "price": 9500,
    "vehicle_type": "SDN",
    "title_document": "SA"
  }'

Get a single listing of yours

curl https://onlysalvage.com/api/v1/listings/123/ \
  -H "Authorization: Bearer osk_your_token_here"

Edit a listing's fields (partial updates supported)

curl -X PATCH https://onlysalvage.com/api/v1/listings/123/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"price": 8900, "description": "Price reduced -- motivated seller."}'

Permanently delete a listing and its photos

curl -X DELETE https://onlysalvage.com/api/v1/listings/123/ \
  -H "Authorization: Bearer osk_your_token_here"

# 204 No Content on success

Change just a listing's status

curl -X POST https://onlysalvage.com/api/v1/listings/123/status/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "AV"}'

Bump an eligible listing back to the top

curl -X POST https://onlysalvage.com/api/v1/listings/123/renew/ \
  -H "Authorization: Bearer osk_your_token_here"

List a listing's photos

curl https://onlysalvage.com/api/v1/listings/123/images/ \
  -H "Authorization: Bearer osk_your_token_here"

Upload a photo, by file or image_url -- add photo_type to upload a damage photo instead of a gallery one

curl -X POST https://onlysalvage.com/api/v1/listings/123/images/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -F "file=@photo.jpg"

# or, from an existing hosted URL instead of a local file:
curl -X POST https://onlysalvage.com/api/v1/listings/123/images/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg"}'

# add photo_type=before_repair to upload a damage photo instead of a
# regular gallery photo (omit it, or send "gallery", for a normal photo):
curl -X POST https://onlysalvage.com/api/v1/listings/123/images/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -F "file=@damage.jpg" \
  -F "photo_type=before_repair"

Remove a single photo

curl -X DELETE https://onlysalvage.com/api/v1/listings/123/images/456/ \
  -H "Authorization: Bearer osk_your_token_here"

# 204 No Content on success

Attach a Carfax, alignment, or inspection report PDF

# Upload the file...
curl -X POST https://onlysalvage.com/api/v1/listings/123/documents/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -F "type=carfax" \
  -F "file=@carfax.pdf"

# ...or just send a link and we'll fetch it. The link must be publicly
# reachable and point straight at the PDF, not at a preview page.
curl -X POST https://onlysalvage.com/api/v1/listings/123/documents/ \
  -H "Authorization: Bearer osk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"type": "carfax", "file_url": "https://example.com/reports/carfax.pdf"}'

Remove a Carfax, alignment, or inspection report

curl -X DELETE "https://onlysalvage.com/api/v1/listings/123/documents/?type=carfax" \
  -H "Authorization: Bearer osk_your_token_here"

# 204 No Content on success

Good to Know

• Requests are rate-limited to 120 per minute per account.
• Every endpoint is scoped to your own listings -- there's no way to read or modify another seller's inventory through this API.
• Validation errors come back as a JSON object mapping field names to error messages, same as the rest of the site's API.
• List responses are paginated (50 per page by default, up to 200 with ?page_size=); use the returned next/previous links to page through the rest.