API docs
Get an API keyA 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:write | create, edit and delete listings and their photos; publish from the plan quota and renew where renewal is free |
credits:spend | with listings:write, pay from the credit balance: paid publication, renewal, TOP placement, highlight, urgent and bump to top |
applications | read job applications, including applicants’ phone and e-mail, and move them between stages |
stats:read | views, 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=1 | Your listings, 50 per page |
POST | /api/v1/listings | Create and publish |
GET | /api/v1/listings/:id | One listing |
PATCH | /api/v1/listings/:id | Change price, title, body or status (active/inactive) |
DELETE | /api/v1/listings/:id | Delete |
POST | /api/v1/listings/:id/images | Add photos (multipart field "photos", up to 10) |
DELETE | /api/v1/listings/:id/images/:image | Remove a photo |
POST | /api/v1/listings/:id/promote | TOP, 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=1 | Applications to your jobs |
PATCH | /api/v1/applications/:id | Move to a stage {"stage": "interview"} |
Stats
GET | /api/v1/me | Account, plan, credits |
GET | /api/v1/stats?days=30 | Views, contacts and saves per day |
Errors
400 | invalid_json · bad_request | The body is not valid JSON |
401 | unauthorized | Missing or invalid key |
402 | insufficient_credits | Not enough credits to publish or promote |
403 | plan_required · account_disabled | Your plan does not include the API, or the account is disabled |
403 | insufficient_scope · spend_cap_reached | The key lacks the permission named in "scope", or the charge would exceed its monthly spending cap |
404 | not_found | Not found, or not yours |
405 | method_not_allowed | Method not supported here (see the Allow header) |
409 | expired · not_published · auction_price_locked · withdrawn · closed · request_in_progress · invalid_status_change · not_deliverable · drafts_limit | Not possible in the current state |
413 | payload_too_large | Request too large (JSON up to 100 kB, photos up to 8 MB) |
415 | unsupported_media_type | Send Content-Type: application/json |
422 | validation_failed · idempotency_key_reused · incomplete · banned_text | Field errors: "fields" (messages) and "codes" (stable keys) |
429 | rate_limited | Rate limit exceeded |
500 | server_error | Something 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_listings | Search by text, category, region, price and filters |
get_listing | Details, price verdict, price history, auction and seller trust |
check_price | Is the price good? Compared with similar cars, flats, houses and phones |
best_offers | Cheapest quarter of the market and the biggest price cuts |
price_trends | Weekly median prices, price cuts and sales |
market_overview | The whole market: volumes, demand, car and flat prices |
find_opportunities | Gigs, jobs, “wanted” ads, lessons, auctions and free give-aways |
list_categories | Categories, 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