Free browsing · direct contact with sellers · no middlemen
Estonia
EN
Categories

API docs

Get an API key

A JSON REST API for listings, candidates and statistics. Prices are in euros, times in ISO 8601.

Partnerships, advertising and API: partners@baltic-market.org

Authentication

Send an Authorization header with a key from “Integrations” on every request. Keep keys on your server.

curl https://baltic-market.org/api/v1/me \
  -H "Authorization: Bearer tg_live_…"

Limit: 120 requests per minute per account, all keys together (X-RateLimit-* headers).

Safe retries

Send an Idempotency-Key header (up to 100 characters) with POST requests. If a connection drops and you retry with the same key and body, you get the first answer back (header Idempotent-Replayed): no second listing, no second charge. Keys are kept for 24 hours.

curl -X POST https://baltic-market.org/api/v1/listings \
  -H "Authorization: Bearer tg_live_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: dms-order-1001" -d '{ … }'

Bodies are JSON objects with the right types; unknown fields and attributes are refused with an explanation. Every response has an X-Request-Id header: quote it when you contact support.

Key permissions

Each key has the permissions ticked when it was made; reading the account (/me) and its listings needs none. New keys get listings:write and stats:read by default. Give each system or vendor its own key with only what it needs. GET /api/v1/me shows the calling key’s permissions and spending.

listings:writecreate, edit and delete listings and their photos; publish from the plan quota and renew where renewal is free
credits:spendwith listings:write, pay from the credit balance: paid publication, renewal, TOP placement, highlight, urgent and bump to top
applicationsread job applications, including applicants’ phone and e-mail, and move them between stages
stats:readviews, contact reveals and saves per day

A key can have a monthly spending cap in credits (calendar month, Latvian time). A charge over the cap is refused with 403 spend_cap_reached, and one by a key without credits:spend with 403 insufficient_scope; nothing is charged. These refusals are not stored for Idempotency-Key, so the same request sent again later (through a key with a higher cap, or next month) is processed afresh. A new listing that would cost credits then stays a draft, with the reason in "pending". Keys made before permissions existed have all of them and no cap: replace them with new ones.

Listings

GET/api/v1/listings?status=active&page=1Your listings, 50 per page
POST/api/v1/listingsCreate and publish
GET/api/v1/listings/:idOne listing
PATCH/api/v1/listings/:idChange price, title, body or status (active/inactive)
DELETE/api/v1/listings/:idDelete
POST/api/v1/listings/:id/imagesAdd photos (multipart field "photos", up to 10)
DELETE/api/v1/listings/:id/images/:imageRemove a photo
POST/api/v1/listings/:id/promoteTOP, highlight, urgent, bump or renewal, paid from credits
curl -X POST https://baltic-market.org/api/v1/listings \
  -H "Authorization: Bearer tg_live_…" -H "Content-Type: application/json" \
  -d '{
    "category": "transport/cars", "deal": "sell",
    "title": "Volkswagen Golf 1.6 TDI, 2015",
    "body": "Serviced at the dealer, one owner, winter tyres included.",
    "price": 8500, "region": "riga", "city": "Purvciems",
    "attrs": { "brand": "Volkswagen", "model": "Golf", "year": 2015, "mileage": 180000, "fuel": "diesel" },
    "days": 30,
    "seller_kind": "trader",
    "trader": { "name": "Auto SIA", "reg_no": "40003000000", "address": "Brīvības iela 1, Rīga", "certified": true }
  }'

Publishing uses your plan quota, then credits. If credits are short, the response contains "pending": "credits" and the listing stays a draft.

Say who is selling (EU Digital Services Act): "seller_kind": "private" or "trader"; a business also sends "trader" with its name, registration number, address and "certified": true, its commitment to offer only products and services that comply with EU law. Without it a listing stays a draft (pending "seller_kind") until you have declared it once on the site.

curl -X POST https://baltic-market.org/api/v1/listings/123/images   -H "Authorization: Bearer tg_live_…" -F "photos=@front.jpg" -F "photos=@interior.jpg"

curl -X POST https://baltic-market.org/api/v1/listings/123/promote   -H "Authorization: Bearer tg_live_…" -H "Content-Type: application/json"   -d '{ "top": 7, "highlight": 7, "bump": true }'

top / highlight / urgent: 7, 14 or 30 days; renew: 7, 14, 30 or 60; bump: true. Your plan discount applies; the amount is in "charged".

Applications

GET/api/v1/applications?listing=:id&page=1Applications to your jobs
PATCH/api/v1/applications/:idMove to a stage {"stage": "interview"}

Stats

GET/api/v1/meAccount, plan, credits
GET/api/v1/stats?days=30Views, contacts and saves per day

Errors

400invalid_json · bad_requestThe body is not valid JSON
401unauthorizedMissing or invalid key
402insufficient_creditsNot enough credits to publish or promote
403plan_required · account_disabledYour plan does not include the API, or the account is disabled
403insufficient_scope · spend_cap_reachedThe key lacks the permission named in "scope", or the charge would exceed its monthly spending cap
404not_foundNot found, or not yours
405method_not_allowedMethod not supported here (see the Allow header)
409expired · not_published · auction_price_locked · withdrawn · closed · request_in_progress · invalid_status_change · not_deliverable · drafts_limitNot possible in the current state
413payload_too_largeRequest too large (JSON up to 100 kB, photos up to 8 MB)
415unsupported_media_typeSend Content-Type: application/json
422validation_failed · idempotency_key_reused · incomplete · banned_textField errors: "fields" (messages) and "codes" (stable keys)
429rate_limitedRate limit exceeded
500server_errorSomething failed on our side; quote the X-Request-Id response header when contacting support

MCP server for AI assistants

Connect Tirgus market data to Claude or any other MCP client: the assistant can search listings, value prices, find the best offers, follow price trends and discover ways to earn. Public, read-only data: no contact details or personal data.

search_listingsSearch by text, category, region, price and filters
get_listingDetails, price verdict, price history, auction and seller trust
check_priceIs the price good? Compared with similar cars, flats, houses and phones
best_offersCheapest quarter of the market and the biggest price cuts
price_trendsWeekly median prices, price cuts and sales
market_overviewThe whole market: volumes, demand, car and flat prices
find_opportunitiesGigs, jobs, “wanted” ads, lessons, auctions and free give-aways
list_categoriesCategories, filters and regions

Remote (HTTP)

In Claude: Settings → Connectors → Add custom connector, and enter this URL. No key needed; limited to 120 units a minute: each request counts 1, and check_price, best_offers, price_trends, market_overview and find_opportunities count 5. The limit counts per IPv4 address or IPv6 /48 network; when the service is busy, clients making only a few calls a minute are still served, and only an overload makes everyone wait (see Retry-After).

https://baltic-market.org/mcp

Local (stdio)

In the Claude Desktop or IDE configuration (on a copy of the server with the same database):

{
  "mcpServers": {
    "tirgus": {
      "command": "node", "args": ["/path/to/market/scripts/mcp-stdio.js"],
      "env": { "MARKET_DB": "/path/to/market/data/production/market.db", "MARKET_ORIGIN": "https://baltic-market.org" }
    }
  }
}

Ready-made prompts: market_report, deal_hunter, earn_money.

CSV

The first CSV row holds column names; attributes use the a_ prefix (same as filters). Separate multiple values with |. Comma or semicolon both work.

category,deal,title,body,price,region,city,a_brand,a_model,a_year
transport/cars,sell,"Škoda Octavia 2.0 TDI","Serviced, new tyres, two keys.",9900,riga,Teika,Skoda,Octavia,2017