Raw schema
{
"type": "object",
"properties": {
"query": {
"description": "Natural-language search (e.g. \"sommelier in Paris fine dining\"). When provided, ranks by semantic similarity. When omitted, returns latest jobs filtered + sorted by the structured options.",
"type": "string"
},
"country": {
"description": "ISO-3166 alpha-2 country code, e.g. FR, GB, ES.",
"type": "string"
},
"city": {
"description": "City name (exact match against hosco_location.locality).",
"type": "string"
},
"department": {
"description": "Hosco category code, e.g. f-b-kitchen, housekeeping, sommelier, reception.",
"type": "string"
},
"content_language": {
"description": "Language code the job ad itself is written in (auto-detected), e.g. \"en\", \"fr\". Use this to only show postings the candidate can actually read — unrelated to the languages filter below.",
"type": "string"
},
"contract_type": {
"description": "One of: internship (students only), professional (professionals only), open (both).",
"type": "string"
},
"experience_years_max": {
"description": "Maximum years of experience the candidate has — only show jobs requiring less than or equal to this.",
"type": "integer"
},
"languages": {
"description": "Candidate language codes, e.g. [\"en\",\"fr\"]. Matched against the job's mandatory fluency requirement (\"Require fluency in\" in hosco-v2), not the language the ad is written in. Combined with languages_mode.",
"items": {
"type": "string"
},
"type": "array"
},
"languages_mode": {
"description": "How to interpret `languages`: \"all\" (job must require every code; default), \"any\" (job requires at least one of them), \"subset\" (job's required languages must all be in the provided list — i.e. the candidate speaks them all).",
"type": "string"
},
"visibilities": {
"description": "Visibility tiers to include: public, targeted, lite, prime (private is never returned on this public surface).",
"items": {
"type": "string"
},
"type": "array"
},
"promotion_types": {
"description": "Filter to specific promotion statuses: 0=disabled, 1=prime, 2=lite-basic, 4=lite-full. Status 3 (private) is always excluded.",
"items": {
"type": "integer"
},
"type": "array"
},
"only_external": {
"description": "Only return jobs sourced from external aggregators.",
"type": "boolean"
},
"hide_external": {
"description": "Hide jobs sourced from external aggregators (Hosco-native only).",
"type": "boolean"
},
"posted_after": {
"description": "ISO date; only return jobs published on or after this date.",
"type": "string"
},
"sort": {
"description": "Ordering: \"suggested\" (default — relevance, then Hosco-native, then VIP, then freshness), \"posted\" (newest activation date), \"update_date\" (most recently updated), \"title\" (alphabetical).",
"type": "string"
},
"limit": {
"description": "Page size (1–50, default 10).",
"minimum": 1,
"maximum": 50,
"type": "integer"
},
"offset": {
"description": "Pagination offset (default 0).",
"minimum": 0,
"type": "integer"
}
}
}