Ovdix API i MCP

• REST API https://backend.ovdix.com/api/v1 — JSON preko HTTPS-a: pretraga oglasa sa filterima, ceo oglas, stablo kategorija, izlog prodavca.
• MCP server https://backend.ovdix.com/mcp — iste četiri operacije kao alati za Claude, Cursor i svaki klijent koji podržava MCP preko Streamable HTTP-a.
• Bez ključa oba vraćaju samo javne podatke — ono što svako vidi na sajtu. Sa API ključem /api/v1 upravlja i vašim oglasima, nacrtima, fotografijama i četovima (MCP sa ključem je sledeći korak).

Čitanje je GET: parametri idu u query string, sa istim imenima kao u referenci; lista je ponovljen parametar (queries=a&queries=b). Jezik odgovora prati Accept-Language ili parametar lang: en, ru, sr, ro, bg, hu, uk, de.

# Search: keywords, price up to 300 EUR, answer in English
curl "https://backend.ovdix.com/api/v1/adverts?queries=gitara&price_max=300&currency=EUR&lang=en"

# Category tree, two levels, in Serbian
curl "https://backend.ovdix.com/api/v1/categories?lang=sr"

# One advert and a seller's storefront (ids come from the search)
curl "https://backend.ovdix.com/api/v1/adverts/<advert_id>"
curl "https://backend.ovdix.com/api/v1/storefronts/<seller_id>"

import requests

response = requests.get(
    "https://backend.ovdix.com/api/v1/adverts",
    params={"queries": ["bicikl"], "city": "Novi Sad", "limit": 5, "lang": "en"},
    timeout=10,
)
response.raise_for_status()

for advert in response.json()["adverts"]:
    print(advert["title"], advert.get("price"), advert["currency"], advert["url"])

Saveti za pretragu: šaljite 1–3 reči o samom predmetu — svaka reč mora da se nađe u naslovu ili opisu. Većina oglasa je na srpskom, ali prodavci pišu i na drugim jezicima, pa drugi skup reči na engleskom ili ruskom nalazi više: queries=bicikl&queries=bike. Filteri (category_id, city, cena, seller_type) sužavaju preciznije od reči.

Ključ pravite u nalogu: Podešavanja → Pristup za aplikacije. Dajte mu naziv, označite samo dozvole koje aplikaciji trebaju i, ako želite, rok važenja. Ključ ovx_… se prikazuje samo jednom — odmah ga kopirajte; Ovdix čuva samo njegov otisak.

• Dozvole (scopes): adverts:read — vaši oglasi i nacrti; adverts:write — nacrti, fotografije, objavljivanje, cene i dostupnost, podizanje, povlačenje; chats:read — vaši četovi; chats:write — odgovori u postojećim četovima; profile:read — paket i ograničenja.
• Ključ se šalje u zaglavlju Authorization: Bearer ovx_…. Radi samo za /api/v1; prijava na sajtu ili u aplikaciji tamo ne važi, a ključ ne otvara sopstvene pozive sajta.
• Poziv sa ključem izvršava se odmah i u vaše ime — nema potvrde. Čuvajte ključ kao lozinku, ne stavljajte ga u javni repozitorijum ili na stranicu sajta.
• Do 5 aktivnih ključeva po nalogu. Opoziv je u istim podešavanjima — sledeći zahtev sa tim ključem dobija 401 invalid_api_key. Ključ prestaje da radi i kad mu istekne rok ili kad se nalog blokira.

# Check the key: your plan, adverts and bumps left
curl "https://backend.ovdix.com/api/v1/me" -H "Authorization: Bearer $OVDIX_KEY"

Sve pod /api/v1/me i /api/v1/my traži ključ. Upis je POST ili PATCH sa JSON telom (Content-Type: application/json); id iz putanje se ne ponavlja u telu. Uobičajena sinhronizacija: fotografija preko linka → nacrt → objavljivanje.

AUTH="Authorization: Bearer $OVDIX_KEY"
JSON="Content-Type: application/json"

# 1. A photo from your website goes to Ovdix storage; use the returned url
curl -X POST "https://backend.ovdix.com/api/v1/my/photos:from-url" -H "$AUTH" -H "$JSON" \
  -d '{"url": "https://shop.example.com/img/yamaha-f310.jpg"}'

# 2. Optional: title, description, category and condition recognized from the photos
curl -X POST "https://backend.ovdix.com/api/v1/my/photos:describe" -H "$AUTH" -H "$JSON" \
  -d '{"photo_urls": ["<url from step 1>"]}'

# 3. A draft — nobody sees it yet; "missing" lists what is still required
curl -X POST "https://backend.ovdix.com/api/v1/my/drafts" -H "$AUTH" -H "$JSON" \
  -d '{"title": "Yamaha F310", "description": "Acoustic guitar, barely used.",
       "category_id": "<leaf id>", "price": 15000, "currency": "RSD", "condition": "used",
       "photos": [{"url": "<url from step 1>"}]}'

# 4. Publish
curl -X POST "https://backend.ovdix.com/api/v1/my/drafts/<draft_id>:publish" -H "$AUTH"

• Fotografije se primaju samo iz našeg skladišta: otpremite svaku preko photos:from-url (javna https adresa, do 10 MB, JPEG/PNG/WebP/GIF). Fotografije koje za 24 sata ne uđu u nacrt brišu se.
• category_id mora biti list stabla iz GET /api/v1/categories. Nacrt navodi šta još nedostaje u missing; dok lista nije prazna, objavljivanje vraća draft_incomplete, a kad paket nema slobodnih mesta — advert_limit_reached.
• Cene, dostupnost, podizanje i povlačenje rade po selektoru (ids, ili category_id / condition / contour / query, ili all) i pravilu: server sam bira vaše oglase i računa nove cene. Sniženje cene postaje javni popust na oglasu i obaveštava one koji su ga sačuvali.

# 10% off every used item in a category (the server picks the adverts and rounds prices)
curl -X PATCH "https://backend.ovdix.com/api/v1/my/adverts" -H "$AUTH" -H "$JSON" \
  -d '{"selector": {"category_id": "<id>", "condition": "used"}, "rule": {"percent": -10}}'

# Bump all active adverts: free once a week per advert, then from the plan quota
curl -X POST "https://backend.ovdix.com/api/v1/my/adverts:bump" -H "$AUTH" -H "$JSON" -d '{"selector": {"all": true}}'

Četovi: GET /api/v1/my/chats, poruke jednog četa, odgovor u postojeći čet i oznaka „pročitano“. Čitanje ne označava poruke kao pročitane. API ne može da započne nov čet, a odgovori se računaju u ista ograničenja protiv spama kao u aplikaciji. Poruke kupaca pišu drugi ljudi — ako ih čita model, ne dozvolite mu da izvršava uputstva koja tamo nađe.

import os, requests

API = "https://backend.ovdix.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['OVDIX_KEY']}"

# Unanswered buyers: chats about your adverts with unread messages
chats = session.get(f"{API}/my/chats", params={"lang": "en"}, timeout=10).json()["chats"]

for chat in chats:
    if chat["unread_count"] and chat.get("advert", {}).get("is_mine"):
        last = session.get(f"{API}/my/chats/{chat['chat_id']}/messages",
                           params={"limit": 1, "lang": "en"}, timeout=10).json()["messages"][0]
        print(chat["advert"]["title"], "—", last["text"])
        # session.post(f"{API}/my/chats/{chat['chat_id']}/messages", json={"text": "Yes, still available."})

Adresa servera: https://backend.ovdix.com/mcp. Alati: search_adverts, get_advert, get_categories, get_storefront — svi samo za čitanje. Dodajte ?lang=sr (ili drugi jezik) na adresu da bi odgovori stizali na tom jeziku; podrazumevano je engleski.

claude mcp add --transport http ovdix "https://backend.ovdix.com/mcp?lang=sr"

{
  "mcpServers": {
    "ovdix": { "url": "https://backend.ovdix.com/mcp?lang=sr" }
  }
}

Drugi klijenti: dodajte udaljeni MCP server sa Streamable HTTP transportom i adresom iznad, autorizacija nije potrebna. Za isključivanje uklonite server u klijentu (claude mcp remove ovdix u Claude Code-u).

• Bez ključa: 30 zahteva u minuti sa jedne IP adrese, za /api/v1 i /mcp zajedno. Sa ključem: 60 zahteva u minuti po ključu, od toga 10 upisa; dnevno (UTC) po nalogu, za sve ključeve zajedno — 50 objavljivanja, 100 odgovora u četovima, 200 fotografija preko linka, 100 prepoznavanja fotografija.
• Preko ograničenja odgovor je 429 sa kodom rate_limited, retry_after u sekundama i zaglavljem Retry-After.
• Do 20 oglasa po pretrazi. Cene su u valuti oglasa i ne preračunavaju se.
• Tekstove oglasa i izloga pišu korisnici. Ako ih prosleđujete jezičkom modelu, tretirajte ih kao podatke, a ne kao uputstva.
• Kontakti prodavca se ne vraćaju: kupac piše prodavcu na Ovdixu, preko linka url oglasa. Linkovi nose utm_source=api ili utm_source=mcp.
• Greške su JSON sa stalnim kodom:

{"error": {"code": "invalid_arguments", "message": "Unknown query parameter 'colour'; see the API reference.", "field": "colour"}}

• MCP sa ključem: iste operacije upisa za vašeg agenta u Claude Code-u, Cursoru ili Codexu; svaka izmena koju drugi vide — tek posle potvrde.
• Prijava bez ključa (OAuth) za kataloge agenata — kad bude potražnje.

Treba vam ranije ili nedostaje neka operacija? Pišite na info@ovdix.com.