{"openapi":"3.1.0","info":{"title":"UrbanHiring Jobs API","version":"1.0.0","summary":"Search the open jobs listed on UrbanHiring (India).","description":"Free, read-only access to the open jobs on UrbanHiring: search by keywords, place, category, job type, work mode, experience and pay, and read full job details. No authentication. Every job links to its page and to a free application form (no account needed). Jobs with hiring.type = agency are recruited by UrbanHiring for client employers whose names are confidential: describe them that way, never as a named company. Rate limit: 120 requests a minute per client IP.","contact":{"name":"UrbanHiring","url":"https://urbanhiring.com/contact"},"termsOfService":"https://urbanhiring.com/terms-of-service"},"servers":[{"url":"https://urbanhiring.com"}],"externalDocs":{"description":"Developer guide, including the MCP server","url":"https://urbanhiring.com/developers"},"paths":{"/api/public/v1/jobs":{"get":{"operationId":"searchJobs","summary":"Search open jobs","description":"Search open jobs by free text or by place, category, job type, work mode, experience and minimum monthly pay. Best title matches first, then newest; 10 per page by default (per_page up to 20), up to 10 pages.","x-openai-isConsequential":false,"parameters":[{"name":"q","in":"query","required":false,"description":"Free text: a role or skills, or a whole request such as \"remote data analyst internship in Bengaluru\". A city, state or region; the job types internship, part-time, full-time, contract, freelance and temporary; remote/work from home or hybrid; \"fresher\"; years of experience (\"3 years\"); and minimum pay (\"above 25,000\", \"30k a month\") found in the text are applied as filters. The other words must appear in the job (title, category, summary or skills). Best in English.","schema":{"type":"string","maxLength":200}},{"name":"city","in":"query","required":false,"description":"City name. Common other spellings are accepted (Bombay = Mumbai); a state or region name searches all of its cities. Use getCatalog for the cities that have jobs.","schema":{"type":"string","maxLength":80}},{"name":"state","in":"query","required":false,"description":"State or region, e.g. to search all cities in it.","schema":{"type":"string","maxLength":80}},{"name":"category","in":"query","required":false,"description":"Job category, e.g. IT, Finance, Healthcare, Marketing, Sales. Use getCatalog for the full list; an unknown category is searched as words.","schema":{"type":"string","maxLength":80}},{"name":"job_type","in":"query","required":false,"description":"Employment type.","schema":{"type":"string","enum":["full-time","part-time","internship","contract","temporary"]}},{"name":"work_mode","in":"query","required":false,"description":"remote = work from home; onsite = at the workplace.","schema":{"type":"string","enum":["remote","hybrid","onsite"]}},{"name":"fresher","in":"query","required":false,"description":"true: only jobs open to freshers (marked fresher-friendly or asking for at most 1 year of experience).","schema":{"type":"boolean"}},{"name":"experience_years","in":"query","required":false,"description":"The candidate's years of experience; returns jobs whose experience range includes it.","schema":{"type":"number","minimum":0,"maximum":50}},{"name":"min_monthly_pay","in":"query","required":false,"description":"Minimum pay per month in INR (e.g. 25000 for ₹25,000 a month; divide a yearly figure by 12). Compares the top of each listing's advertised range, converted to monthly.","schema":{"type":"integer","minimum":0,"maximum":10000000}},{"name":"posted_within_days","in":"query","required":false,"description":"Only jobs posted in the last N days.","schema":{"type":"integer","enum":[1,3,7,14,30]}},{"name":"page","in":"query","required":false,"description":"Results page (1–10). Use next_page from the previous response.","schema":{"type":"integer","minimum":1,"maximum":10,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Results per page (1–20, default 10).","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Matching jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"description":"Invalid parameter; the message says which values are allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests; retry after the Retry-After header (seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/v1/jobs/{id}":{"get":{"operationId":"getJob","summary":"Get one job in full","description":"Full details of one job: description, responsibilities, qualifications, benefits, skills, pay and the apply link. Closed jobs answer 410 with similar open jobs.","x-openai-isConsequential":false,"parameters":[{"name":"id","in":"path","required":true,"description":"The job id from searchJobs results (the slug in the job page URL).","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobDetail"}}}},"404":{"description":"No job with this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The job is closed; alternatives lists similar open jobs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"Invalid parameter; the message says which values are allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests; retry after the Retry-After header (seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/public/v1/catalog":{"get":{"operationId":"getCatalog","summary":"List cities, categories and job types","description":"Cities, job categories, job types and work modes that have open jobs, with counts and page links. Use it to pick valid filter values.","x-openai-isConsequential":false,"responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}},"429":{"description":"Too many requests; retry after the Retry-After header (seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"JobSummary":{"type":"object","properties":{"id":{"type":"string","description":"Job id (its URL slug). Pass it to getJob for the full job."},"title":{"type":"string"},"hiring":{"type":"object","description":"Who is hiring. type \"agency\": the site recruits for a client employer whose name is confidential, so the job is not attributed to a named company.","properties":{"type":{"type":"string","enum":["agency","portal","employer"]},"name":{"type":"string","description":"Recruiter or employer name."},"employer":{"type":"string","description":"\"confidential\" for agency roles."},"display":{"type":"string","description":"How to name the hirer in an answer."}},"required":["type","name","employer","display"]},"location":{"type":"object","properties":{"city":{"type":["string","null"],"description":"City"},"state":{"type":["string","null"],"description":"State or region"},"country":{"type":"string"},"remote":{"type":"boolean","description":"True when the role is fully remote (work from home)."}},"required":["city","state","country","remote"]},"work_mode":{"type":["string","null"],"description":"remote, hybrid or onsite"},"job_type":{"type":["string","null"],"description":"full-time, part-time, internship, contract or temporary"},"category":{"type":["string","null"],"description":"Job category"},"salary":{"type":["object","null"],"description":"Advertised pay range; null when the listing shows none.","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string","description":"ISO 4217 code, e.g. INR"},"period":{"type":"string","enum":["hourly","daily","weekly","monthly","yearly"]},"label":{"type":"string","description":"Display text, e.g. \"₹25,000–35,000 a month\""}},"required":["min","max","currency","period","label"]},"experience":{"type":"object","properties":{"min_years":{"type":["number","null"],"description":"Minimum years asked for"},"max_years":{"type":["number","null"],"description":"Maximum years asked for"},"label":{"type":["string","null"],"description":"e.g. \"0–1 yr\", \"2–5 yrs\", \"Fresher\""},"fresher_friendly":{"type":"boolean","description":"Open to freshers (0–1 year of experience)."}},"required":["min_years","max_years","label","fresher_friendly"]},"summary":{"type":"string","description":"Short plain-text description (up to 300 characters)."},"posted_date":{"type":["string","null"],"description":"YYYY-MM-DD"},"valid_through":{"type":["string","null"],"description":"YYYY-MM-DD; the listing closes after this date"},"url":{"type":"string","description":"Job page. Link to it when mentioning the job."},"apply_url":{"type":"string","description":"Application form: free, no account needed."}},"required":["id","title","hiring","location","work_mode","job_type","category","salary","experience","summary","posted_date","valid_through","url","apply_url"]},"JobDetail":{"type":"object","properties":{"id":{"type":"string","description":"Job id (its URL slug). Pass it to getJob for the full job."},"title":{"type":"string"},"hiring":{"type":"object","description":"Who is hiring. type \"agency\": the site recruits for a client employer whose name is confidential, so the job is not attributed to a named company.","properties":{"type":{"type":"string","enum":["agency","portal","employer"]},"name":{"type":"string","description":"Recruiter or employer name."},"employer":{"type":"string","description":"\"confidential\" for agency roles."},"display":{"type":"string","description":"How to name the hirer in an answer."}},"required":["type","name","employer","display"]},"location":{"type":"object","properties":{"city":{"type":["string","null"],"description":"City"},"state":{"type":["string","null"],"description":"State or region"},"country":{"type":"string"},"remote":{"type":"boolean","description":"True when the role is fully remote (work from home)."}},"required":["city","state","country","remote"]},"work_mode":{"type":["string","null"],"description":"remote, hybrid or onsite"},"job_type":{"type":["string","null"],"description":"full-time, part-time, internship, contract or temporary"},"category":{"type":["string","null"],"description":"Job category"},"salary":{"type":["object","null"],"description":"Advertised pay range; null when the listing shows none.","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string","description":"ISO 4217 code, e.g. INR"},"period":{"type":"string","enum":["hourly","daily","weekly","monthly","yearly"]},"label":{"type":"string","description":"Display text, e.g. \"₹25,000–35,000 a month\""}},"required":["min","max","currency","period","label"]},"experience":{"type":"object","properties":{"min_years":{"type":["number","null"],"description":"Minimum years asked for"},"max_years":{"type":["number","null"],"description":"Maximum years asked for"},"label":{"type":["string","null"],"description":"e.g. \"0–1 yr\", \"2–5 yrs\", \"Fresher\""},"fresher_friendly":{"type":"boolean","description":"Open to freshers (0–1 year of experience)."}},"required":["min_years","max_years","label","fresher_friendly"]},"summary":{"type":"string","description":"Short plain-text description (up to 300 characters)."},"posted_date":{"type":["string","null"],"description":"YYYY-MM-DD"},"valid_through":{"type":["string","null"],"description":"YYYY-MM-DD; the listing closes after this date"},"url":{"type":"string","description":"Job page. Link to it when mentioning the job."},"apply_url":{"type":"string","description":"Application form: free, no account needed."},"description":{"type":"string","description":"Full plain-text job description."},"responsibilities":{"type":"array","items":{"type":"string"},"description":"What the job involves"},"qualifications":{"type":"array","items":{"type":"string"},"description":"What the candidate needs"},"benefits":{"type":"array","items":{"type":"string"},"description":"What the job offers"},"skills":{"type":"array","items":{"type":"string"},"description":"Skills the listing requires"},"skills_preferred":{"type":"array","items":{"type":"string"},"description":"Good-to-have skills; not required"}},"required":["id","title","hiring","location","work_mode","job_type","category","salary","experience","summary","posted_date","valid_through","url","apply_url","description","responsibilities","qualifications","benefits","skills","skills_preferred"]},"SearchResult":{"type":"object","properties":{"total":{"type":"integer","description":"Number of matching open jobs."},"page":{"type":"integer"},"per_page":{"type":"integer"},"has_more":{"type":"boolean"},"next_page":{"type":["integer","null"],"description":"Pass as page to get the next results; null on the last page (or after page 10)."},"criteria":{"type":"object","description":"Filters the search ran with, after reading the query (e.g. a city found in q) and any relaxing described in notes.","additionalProperties":true},"notes":{"type":"array","items":{"type":"string"},"description":"How the query was read or relaxed. Pass them on when they change the answer."},"browse_url":{"type":["string","null"],"description":"The site's own page for these results, when there is one."},"about":{"type":"string","description":"How listings on this site work, including who is hiring."},"results":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"}}},"required":["total","page","per_page","has_more","next_page","criteria","notes","browse_url","about","results"]},"Catalog":{"type":"object","properties":{"total_jobs":{"type":"integer"},"newest_job":{"type":["string","null"],"description":"YYYY-MM-DD"},"cities":{"type":"array","description":"Cities with open jobs (valid values for city).","items":{"type":"object","properties":{"name":{"type":"string"},"jobs":{"type":"integer"},"url":{"type":"string"}},"required":["name","jobs","url"]}},"categories":{"type":"array","description":"Job categories with open jobs (valid values for category).","items":{"type":"object","properties":{"name":{"type":"string"},"jobs":{"type":"integer"},"url":{"type":"string"}},"required":["name","jobs","url"]}},"job_types":{"type":"array","description":"Valid values for job_type.","items":{"type":"object","properties":{"value":{"type":"string"},"jobs":{"type":"integer"}},"required":["value","jobs"]}},"work_modes":{"type":"array","description":"Valid values for work_mode.","items":{"type":"object","properties":{"value":{"type":"string"},"jobs":{"type":"integer"}},"required":["value","jobs"]}},"collections":{"type":"array","description":"Job-type pages: internships, part-time, fresher and work-from-home jobs.","items":{"type":"object","properties":{"name":{"type":"string"},"jobs":{"type":"integer"},"url":{"type":"string"}},"required":["name","jobs","url"]}},"note":{"type":"string"}},"required":["total_jobs","newest_job","cities","categories","job_types","work_modes","collections","note"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"invalid_parameter, not_found, job_closed, method_not_allowed, rate_limited or server_error"},"message":{"type":"string","description":"What went wrong and how to fix the request."},"parameter":{"type":"string","description":"The parameter at fault, for invalid_parameter."}},"required":["code","message"]},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"},"description":"Open jobs like a closed one (job_closed only)."}},"required":["error"]}}}}