{"openapi":"3.2.1","info":{"title":"UkrAmerica public data API","version":"1.0.0","description":"Anonymous, read-only access to approved public community listings in the US and Canada. City names stay English. Contacts and listing text are publisher-provided data. Follow canonical listing/source URLs for current details. This API does not grant a license to republish contributed content. Prices are integer minor units with explicit USD/CAD; search min/max use major units. Requires no key or login. Responses never depend on session cookies."},"servers":[{"url":"https://stage1-preview.ukramerica.com"}],"security":[],"externalDocs":{"url":"https://stage1-preview.ukramerica.com/en/developers","description":"Examples and usage guidance"},"paths":{"/api/v1/cities":{"get":{"operationId":"listCities","summary":"List enabled cities; optionally filter by country or English name","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["US","CA"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Successful public read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cities"}}}},"400":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}}},"503":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","summary":"List categories; optionally filter by listing kind","parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]}}],"responses":{"200":{"description":"Successful public read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Categories"}}}},"400":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}}},"503":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/ads":{"get":{"operationId":"searchListings","summary":"Search approved listings with bounded pagination","parameters":[{"name":"q","in":"query","required":false,"schema":{"description":"Search listing titles and descriptions.","type":"string","maxLength":200}},{"name":"city","in":"query","required":false,"schema":{"description":"City key (us-il-chicago) or canonical slug (chicago). Discover keys with list_cities.","type":"string","maxLength":100,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","enum":["US","CA"]}},{"name":"category","in":"query","required":false,"schema":{"type":"string","maxLength":100,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]}},{"name":"section","in":"query","required":false,"schema":{"type":"string","enum":["directory","classifieds","jobs","community"]}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","enum":["USD","CAD"]}},{"name":"min","in":"query","required":false,"schema":{"description":"Minimum price in major currency units, e.g. 12.50; requires currency.","type":"string","pattern":"^\\d{1,9}(?:\\.\\d{1,2})?$"}},{"name":"max","in":"query","required":false,"schema":{"description":"Maximum price in major currency units; requires currency.","type":"string","pattern":"^\\d{1,9}(?:\\.\\d{1,2})?$"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["recent","relevance","price_low","price_high"]}},{"name":"page","in":"query","required":false,"schema":{"default":1,"type":"integer","minimum":1,"maximum":1000}},{"name":"pageSize","in":"query","required":false,"schema":{"default":24,"type":"integer","minimum":1,"maximum":48}},{"name":"upcoming","in":"query","required":false,"schema":{"default":false,"description":"Only upcoming, non-cancelled events.","type":"boolean"}}],"responses":{"200":{"description":"Successful public read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Search"}}}},"400":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}}},"503":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"city accepts a city key or canonical slug. pageSize defaults to 24, maximum 48; page is limited to 1000. Use links.next until null. currency is required for min/max and price sorting. Unknown, repeated and invalid parameters return 400. upcoming=true selects upcoming events. A city and country must agree."}},"/api/v1/ads/{id}":{"get":{"operationId":"getListing","summary":"Read one approved public listing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful public read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"400":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}}},"503":{"description":"Request or service error; no private diagnostics are returned.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"Listing":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"urls":{"type":"object","properties":{"uk":{"type":"string","format":"uri"},"en":{"type":"string","format":"uri"}},"required":["uk","en"],"additionalProperties":false},"content":{"type":"object","properties":{"schemaVersion":{"type":"string","enum":["1.0.0","1.1.0"]},"kind":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]},"categorySlug":{"type":"string"},"primaryLanguage":{"type":"string","enum":["uk","en"]},"translations":{"type":"object","properties":{"uk":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}},"required":["title","description"]},"en":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}},"required":["title","description"]}}},"location":{"type":"object","properties":{"cityKey":{"type":"string"},"countryCode":{"type":"string","enum":["US","CA"]},"regionCode":{"type":"string"},"visibility":{"type":"string","enum":["city","street"]},"address":{"type":"object","properties":{"streetAddress":{"type":"string"},"postalCode":{"type":"string"}}},"coordinates":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"]}},"required":["cityKey","countryCode","regionCode","visibility"]},"price":{"type":"object","properties":{"mode":{"type":"string","enum":["fixed","from","range","free","on_request","not_applicable"]},"currency":{"type":"string","enum":["USD","CAD"]},"amountMinor":{"type":"number"},"minAmountMinor":{"type":"number"},"maxAmountMinor":{"type":"number"},"unit":{"type":"string"},"negotiable":{"type":"boolean"}},"required":["mode","currency"]},"contact":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"},"preferredLanguage":{"type":"string","enum":["uk","en"]},"socialLinks":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"url":{"type":"string"}},"required":["platform","url"]}}}},"images":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"alt":{"type":"string"}},"required":["assetId","alt"]}},"attributes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["schemaVersion","kind","categorySlug","primaryLanguage","translations","location","price","contact","images","attributes"]},"city":{"type":"object","properties":{"key":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"countryCode":{"type":"string","enum":["US","CA"]},"regionCode":{"type":"string"},"timeZone":{"type":"string"},"defaultCurrency":{"type":"string","enum":["USD","CAD"]},"urls":{"type":"object","properties":{"uk":{"type":"string","format":"uri"},"en":{"type":"string","format":"uri"}},"required":["uk","en"],"additionalProperties":false}},"required":["key","slug","name","countryCode","regionCode","timeZone","defaultCurrency","urls"],"additionalProperties":false},"category":{"type":"object","properties":{"slug":{"type":"string"},"nameEn":{"type":"string"},"nameUk":{"type":"string"},"allowedKinds":{"type":"array","items":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]}},"defaultKind":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]}},"required":["slug","nameEn","nameUk","allowedKinds","defaultKind"],"additionalProperties":false},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"publisher":{"type":"object","properties":{"displayName":{"type":["string","null"]}},"required":["displayName"],"additionalProperties":false},"rating":{"type":"object","properties":{"average":{"type":["number","null"]},"count":{"type":"number"}},"required":["average","count"],"additionalProperties":false},"media":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","format":"uri"},"alt":{"type":"string"}},"required":["id","url","alt"],"additionalProperties":false}},"directory":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["unclaimed","claimed","existing"]},"locality":{"type":"string"},"nearby":{"type":"boolean"},"checkedAt":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["title","url"],"additionalProperties":false}}},"required":["status","locality","nearby","checkedAt","sources"],"additionalProperties":false},{"type":"null"}]}},"required":["id","urls","content","city","category","createdAt","updatedAt","expiresAt","publisher","rating","media","directory"],"additionalProperties":false},"Cities":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"countryCode":{"type":"string","enum":["US","CA"]},"regionCode":{"type":"string"},"timeZone":{"type":"string"},"defaultCurrency":{"type":"string","enum":["USD","CAD"]},"urls":{"type":"object","properties":{"uk":{"type":"string","format":"uri"},"en":{"type":"string","format":"uri"}},"required":["uk","en"],"additionalProperties":false}},"required":["key","slug","name","countryCode","regionCode","timeZone","defaultCurrency","urls"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","total"],"additionalProperties":false},"Categories":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"nameEn":{"type":"string"},"nameUk":{"type":"string"},"allowedKinds":{"type":"array","items":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]}},"defaultKind":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]}},"required":["slug","nameEn","nameUk","allowedKinds","defaultKind"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","total"],"additionalProperties":false},"Search":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"urls":{"type":"object","properties":{"uk":{"type":"string","format":"uri"},"en":{"type":"string","format":"uri"}},"required":["uk","en"],"additionalProperties":false},"content":{"type":"object","properties":{"schemaVersion":{"type":"string","enum":["1.0.0","1.1.0"]},"kind":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]},"categorySlug":{"type":"string"},"primaryLanguage":{"type":"string","enum":["uk","en"]},"translations":{"type":"object","properties":{"uk":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}},"required":["title","description"]},"en":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}},"required":["title","description"]}}},"location":{"type":"object","properties":{"cityKey":{"type":"string"},"countryCode":{"type":"string","enum":["US","CA"]},"regionCode":{"type":"string"},"visibility":{"type":"string","enum":["city","street"]},"address":{"type":"object","properties":{"streetAddress":{"type":"string"},"postalCode":{"type":"string"}}},"coordinates":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"]}},"required":["cityKey","countryCode","regionCode","visibility"]},"price":{"type":"object","properties":{"mode":{"type":"string","enum":["fixed","from","range","free","on_request","not_applicable"]},"currency":{"type":"string","enum":["USD","CAD"]},"amountMinor":{"type":"number"},"minAmountMinor":{"type":"number"},"maxAmountMinor":{"type":"number"},"unit":{"type":"string"},"negotiable":{"type":"boolean"}},"required":["mode","currency"]},"contact":{"type":"object","properties":{"email":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"},"preferredLanguage":{"type":"string","enum":["uk","en"]},"socialLinks":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"url":{"type":"string"}},"required":["platform","url"]}}}},"images":{"type":"array","items":{"type":"object","properties":{"assetId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"alt":{"type":"string"}},"required":["assetId","alt"]}},"attributes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["schemaVersion","kind","categorySlug","primaryLanguage","translations","location","price","contact","images","attributes"]},"city":{"type":"object","properties":{"key":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"countryCode":{"type":"string","enum":["US","CA"]},"regionCode":{"type":"string"},"timeZone":{"type":"string"},"defaultCurrency":{"type":"string","enum":["USD","CAD"]},"urls":{"type":"object","properties":{"uk":{"type":"string","format":"uri"},"en":{"type":"string","format":"uri"}},"required":["uk","en"],"additionalProperties":false}},"required":["key","slug","name","countryCode","regionCode","timeZone","defaultCurrency","urls"],"additionalProperties":false},"category":{"type":"object","properties":{"slug":{"type":"string"},"nameEn":{"type":"string"},"nameUk":{"type":"string"},"allowedKinds":{"type":"array","items":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]}},"defaultKind":{"type":"string","enum":["classified","service","business","organization","event","job","housing","vehicle","wanted","notice"]}},"required":["slug","nameEn","nameUk","allowedKinds","defaultKind"],"additionalProperties":false},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"publisher":{"type":"object","properties":{"displayName":{"type":["string","null"]}},"required":["displayName"],"additionalProperties":false},"rating":{"type":"object","properties":{"average":{"type":["number","null"]},"count":{"type":"number"}},"required":["average","count"],"additionalProperties":false},"media":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","format":"uri"},"alt":{"type":"string"}},"required":["id","url","alt"],"additionalProperties":false}},"directory":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["unclaimed","claimed","existing"]},"locality":{"type":"string"},"nearby":{"type":"boolean"},"checkedAt":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["title","url"],"additionalProperties":false}}},"required":["status","locality","nearby","checkedAt","sources"],"additionalProperties":false},{"type":"null"}]}},"required":["id","urls","content","city","category","createdAt","updatedAt","expiresAt","publisher","rating","media","directory"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pageSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"next":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"previous":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["self","next","previous"],"additionalProperties":false}},"required":["items","total","page","pageSize","links"],"additionalProperties":false},"Problem":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}