Endpoints, inputs and the response envelope

One endpoint per operation

Each operation has its own endpoint, and every call uses POST. The last path segment is the full action ID, including the polovniautomobili- prefix and hyphens: POST /api/v1/polovniautomobili/polovniautomobili-brands POST /api/v1/polovniautomobili/polovniautomobili-filter-options POST /api/v1/polovniautomobili/polovniautomobili-listing POST /api/v1/polovniautomobili/polovniautomobili-models POST /api/v1/polovniautomobili/polovniautomobili-search

polovniautomobili-brandspolovniautomobili-filter-optionspolovniautomobili-listingpolovniautomobili-modelspolovniautomobili-search

Wrap inputs under body

Send the JSON object {"body": {...}}; input placed outside body fails the operation's schema. Listing requires body.ad_id, a string; body.slug is an optional string. ad_id is the numeric identifier a search result returns, 4–12 digits (pattern \d{4,12}); this site accepts any string for ad_id at admission, and an identifier that is not 4–12 digits may then fail. Models requires body.brand from the closed enum with exact spelling; optional body.sample_pages is an integer from 1 to 10. Brands and filter-options declare no body fields: omit the body property (send {}) or send an empty object as body ({"body":{}}).

body.ad_idbody.slugbody.brandbody.sample_pagespolovniautomobili-brandspolovniautomobili-filter-options

Search bounds and the success envelope

All search fields are optional. body.page is an integer from 1 to 750; body.page_size is one of 25, 50, 100 or 200. A success is {ok:true, data, meta:{requestId, chargedCreditUnits, simulated, sourceAttribution}}. data holds the operation's result and can be null. Even data:null can be a billable success at the operation's approved per-call price.

body.pagebody.page_sizeokdatapriceCreditUnits

Failure codes and uncertain outcomes

An admitted request that fails returns {ok:false, error:{code,message}, meta:{requestId, chargedCreditUnits:"0", status}}, with status "failure" or "uncertain" on the first reply. REQUEST_NOT_FULFILLED (502) means the operation reported that it did not succeed, and REQUEST_REJECTED (502) that it rejected the request; SERVICE_UNAVAILABLE and SERVICE_BUSY (503) describe a condition on the service side, not your key or wallet. These failures are not charged. OPERATION_TIMEOUT (504), OUTCOME_UNKNOWN (504 or 502) and RESULT_INVALID (502) are uncertain: the price is held, then released, and never charged later. Do not retry them under a new Idempotency-Key. Resending the unchanged request with the same key returns its recorded state without running it again: REQUEST_PENDING (409, meta.status "dispatching" or "uncertain") while unresolved, OUTCOME_UNKNOWN_RELEASED (504, meta.status "released", chargedCreditUnits "0") once the hold is released.

errorokdataIdempotency-Key

Admission errors and same-key replay

Errors returned before a request is admitted have the shape {ok:false,error:{code,message},requestId}, with requestId at the top level and no meta. Examples are AUTH_FAILED (401), INSUFFICIENT_CREDITS (402), IDEMPOTENCY_CONFLICT (409), INVALID_REQUEST (400) for a body that is not valid JSON, and INVALID_PARAM (400) for input that fails the operation's schema (types, enums, bounds, required fields). A field inside body that the contract does not declare is handled differently: the request is admitted, then refused with INVALID_INPUT (400), meta.chargedCreditUnits "0" and meta.status "failure". The operation does not run and nothing is charged, but the operation must be enabled and your available credits must cover its price. A stored final response replays its original status and body for 24 hours; after that, a succeeded request returns RESULT_EXPIRED (410, meta.status "succeeded"), which is not a refund, and a failed request returns its recorded error code and HTTP status.

okerrorIdempotency-Key

Discover car brands

POST /api/v1/polovniautomobili/polovniautomobili-brands

Use a JSON object with the documented path, query, headers and body locations; omit unused locations. input.headers is schema-validated data, not browser request headers. Do not put credentials here. Keep body arrays, scalar values and null as documented; omission is different from null.

{
  "body": {}
}

null

Explore filter vocabulary

POST /api/v1/polovniautomobili/polovniautomobili-filter-options

Use a JSON object with the documented path, query, headers and body locations; omit unused locations. input.headers is schema-validated data, not browser request headers. Do not put credentials here. Keep body arrays, scalar values and null as documented; omission is different from null.

{
  "body": {}
}

null

Read a car advertisement

POST /api/v1/polovniautomobili/polovniautomobili-listing

Use a JSON object with the documented path, query, headers and body locations; omit unused locations. input.headers is schema-validated data, not browser request headers. Do not put credentials here. Keep body arrays, scalar values and null as documented; omission is different from null.

{
  "body": {
    "ad_id": "example",
    "slug": "example"
  }
}

null

Find models for a brand

POST /api/v1/polovniautomobili/polovniautomobili-models

Use a JSON object with the documented path, query, headers and body locations; omit unused locations. input.headers is schema-validated data, not browser request headers. Do not put credentials here. Keep body arrays, scalar values and null as documented; omission is different from null.

{
  "body": {
    "brand": "Alfa Romeo",
    "sample_pages": 1
  }
}

null

Search car advertisements

POST /api/v1/polovniautomobili/polovniautomobili-search

Use a JSON object with the documented path, query, headers and body locations; omit unused locations. input.headers is schema-validated data, not browser request headers. Do not put credentials here. Keep body arrays, scalar values and null as documented; omission is different from null.

{
  "body": {
    "air_conditioning": [
      "none"
    ],
    "attest": "attested",
    "body_type": [
      "sedan"
    ],
    "brand": "Alfa Romeo",
    "colour": [
      "white"
    ],
    "country": "RS",
    "country_of_origin": "ME",
    "damaged": [
      "notDamaged"
    ],
    "doors": "3",
    "drive": [
      "front"
    ],
    "emission_class": "euro1",
    "engine_cc_max": 0,
    "engine_cc_min": 0,
    "flywheel": "floatingFlywheel",
    "fuel": [
      "gasoline"
    ],
    "gearbox": [
      "manual4Gears"
    ],
    "interior_colour": [
      "black"
    ],
    "interior_material": [
      "cloth"
    ],
    "listing_age": "all",
    "mileage_max": 0,
    "mileage_min": 0,
    "model": [
      "example"
    ],
    "only_with_price": false,
    "page": 1,
    "page_size": 25,
    "plates": [
      "domesticPlates"
    ],
    "power_kw_max": 0,
    "power_kw_min": 0,
    "price_max": 0,
    "price_min": 0,
    "registered_to_seller": false,
    "seats": "2",
    "trade_in": [
      "noExchange"
    ],
    "wheel_side": "left",
    "year_max": 1900,
    "year_min": 1900
  }
}

null