{"openapi":"3.1.0","info":{"title":"MirageScouting Public API","version":"1.0.0","summary":"Read-only access to the open roles on the MirageScouting job board.","description":"The public, read-only API of MirageScouting, a skills-first hiring platform.\nIt returns the open roles that companies published to the public job board\n(the same data as https://www.miragescouting.de/en/jobs). No authentication is needed.\n\nRate limit: 120 requests per minute per client IP. Every response carries the\nIETF RateLimit and RateLimit-Policy fields (and RateLimit-Limit / -Remaining /\n-Reset); a 429 carries Retry-After in seconds.\n\nCandidate and company search for AI assistants is the MCP server: https://www.miragescouting.de/en/developers/mcp.","termsOfService":"https://www.miragescouting.de/en/terms","contact":{"name":"MirageScouting","url":"https://www.miragescouting.de/en/contact"}},"externalDocs":{"description":"Developer guide","url":"https://www.miragescouting.de/en/developers/api"},"servers":[{"url":"https://www.miragescouting.de/api/v1","description":"Production"}],"security":[],"tags":[{"name":"Jobs","description":"Open roles on the public job board."}],"paths":{"/jobs":{"get":{"operationId":"listJobs","tags":["Jobs"],"summary":"Search open roles","description":"Lists open roles on the public job board, newest first; sponsored roles are pinned on the first page and carry a non-null `promotion`. Filters combine with AND; text filters are case-insensitive substring matches. Page with `nextCursor`.","parameters":[{"name":"query","in":"query","required":false,"description":"Text in the job title.","schema":{"type":"string","maxLength":200,"description":"Text in the job title."}},{"name":"company","in":"query","required":false,"description":"Text in the company name.","schema":{"type":"string","maxLength":200,"description":"Text in the company name."}},{"name":"location","in":"query","required":false,"description":"Text in the location, e.g. Berlin.","schema":{"type":"string","maxLength":200,"description":"Text in the location."}},{"name":"workMode","in":"query","required":false,"description":"Where the work happens.","schema":{"type":"string","enum":["REMOTE","HYBRID","ONSITE"]}},{"name":"seniority","in":"query","required":false,"description":"Seniority level, e.g. SENIOR.","schema":{"type":"string","maxLength":50,"description":"Seniority level."}},{"name":"employmentType","in":"query","required":false,"description":"Employment type, e.g. FULL_TIME.","schema":{"type":"string","maxLength":50,"description":"Employment type."}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","maxLength":512,"description":"Opaque page cursor."}},{"name":"limit","in":"query","required":false,"description":"Page size (default 20).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"A page of open roles.","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPage"}}}},"400":{"description":"Invalid query parameters (`invalid_request`).","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`).","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The job board is temporarily unavailable (`upstream_unavailable`).","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{jobId}":{"get":{"operationId":"getJob","tags":["Jobs"],"summary":"Get one open role","description":"Returns one open role with its full description, benefits and company details. 404 when the role does not exist or is not public (the API never says which).","parameters":[{"name":"jobId","in":"path","required":true,"description":"The job's id (from listJobs).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The open role.","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobDetail"}}}},"400":{"description":"jobId is not a UUID (`invalid_request`).","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No public job with this id (`not_found`).","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (`rate_limited`).","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The job board is temporarily unavailable (`upstream_unavailable`).","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"headers":{"RateLimit":{"description":"IETF RateLimit field: `\"public_jobs\";r=<remaining>;t=<seconds until reset>`.","schema":{"type":"string"}},"RateLimitPolicy":{"description":"IETF RateLimit-Policy field: `\"public_jobs\";q=<quota>;w=<window seconds>`.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"schemas":{"Organisation":{"type":"object","description":"The company that published the role.","required":["id","name","slug","logo","industry"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"logo":{"type":["string","null"],"format":"uri"},"industry":{"type":["string","null"]}}},"OrganisationDetail":{"description":"The company, with its public profile fields.","allOf":[{"$ref":"#/components/schemas/Organisation"},{"type":"object","properties":{"description":{"type":["string","null"]},"tagline":{"type":["string","null"]},"coverImage":{"type":["string","null"],"format":"uri"},"headquarters":{"type":["string","null"]},"website":{"type":["string","null"]},"size":{"type":["string","null"]}}}]},"Salary":{"type":"object","description":"Salary range as published; any part may be missing.","properties":{"min":{"type":["number","null"]},"max":{"type":["number","null"]},"currency":{"type":["string","null"]},"period":{"type":["string","null"]}}},"Promotion":{"type":"object","description":"Disclosure of a paid placement.","required":["label"],"properties":{"label":{"type":"string","enum":["PREMIUM_PARTNER","SPONSORED"]}}},"JobSummary":{"type":"object","description":"An open role as listed on the job board.","required":["id","url","title","tags","organisation"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"The role's public page."},"title":{"type":"string"},"shortDescription":{"type":["string","null"]},"seniority":{"type":["string","null"]},"location":{"type":["string","null"]},"workMode":{"type":["string","null"],"enum":["REMOTE","HYBRID","ONSITE",null]},"employmentType":{"type":["string","null"]},"postedAt":{"type":["string","null"],"format":"date-time"},"applicationDeadline":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"salary":{"anyOf":[{"$ref":"#/components/schemas/Salary"},{"type":"null"}]},"organisation":{"$ref":"#/components/schemas/Organisation"},"promotion":{"anyOf":[{"$ref":"#/components/schemas/Promotion"},{"type":"null"}]}}},"JobDetail":{"type":"object","description":"An open role with its full description.","required":["id","url","title","description","tags","organisation"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"The role's public page."},"title":{"type":"string"},"shortDescription":{"type":["string","null"]},"description":{"type":"string"},"seniority":{"type":["string","null"]},"location":{"type":["string","null"]},"workMode":{"type":["string","null"],"enum":["REMOTE","HYBRID","ONSITE",null]},"employmentType":{"type":["string","null"]},"postedAt":{"type":["string","null"],"format":"date-time"},"applicationDeadline":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"requiredLanguages":{"type":"array","items":{"type":"string"}},"benefits":{"type":"array","items":{"type":"string"}},"numberOfOpenings":{"type":["integer","null"]},"salary":{"anyOf":[{"$ref":"#/components/schemas/Salary"},{"type":"null"}]},"organisation":{"$ref":"#/components/schemas/OrganisationDetail"}}},"JobPage":{"type":"object","description":"One page of open roles.","required":["items","nextCursor"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"}},"nextCursor":{"type":["string","null"]}}},"Error":{"type":"object","description":"Every error has this body.","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","rate_limited","upstream_unavailable"]},"message":{"type":"string"},"details":{"description":"Field errors for invalid_request."}}}}}}}}