{"openapi":"3.1.0","info":{"title":"Oposaketia · Public API","version":"1.0.0","description":"Read-only API for public employment calls and official documents from Euskadi, Navarre and Iparralde. No registration or API key required. CORS allows clients from any origin. Coverage is partial. Official content, source descriptions and stable filter values retain their original language; obtain accepted values from /options. List responses omit topics, requirements and documents (empty arrays); use the detail endpoint to retrieve them. The website keeps qualifications and favorites in the browser."},"servers":[{"url":"/api/v1","description":"API v1 on this server"}],"security":[],"tags":[{"name":"Calls"},{"name":"Sources"},{"name":"Catalogs"},{"name":"Service"}],"paths":{"/calls":{"get":{"operationId":"listCalls","tags":["Calls"],"summary":"Search and paginate public employment calls","description":"Repeat province, category, status, territory, source or qualification to select multiple values. Values within a filter use OR; different filters use AND. Qualification matching is advisory and does not establish eligibility. Filters use the stable values returned by /options. Results have stable ordering with id as a tie-breaker. Out-of-range pages return an empty calls array. Status is evaluated against the current UTC date.","parameters":[{"name":"q","in":"query","description":"Search title, organization, location or province; case-insensitive and accent-insensitive","schema":{"type":"string","maxLength":200}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100000,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":20}},{"name":"sort","in":"query","schema":{"type":"string","enum":["title","deadline","province","status"],"default":"title"}},{"name":"province","in":"query","style":"form","explode":true,"description":"Use Sin concretar for calls without a confirmed province","schema":{"type":"array","items":{"type":"string","enum":["Araba / Álava","Bizkaia","Gipuzkoa","Navarra","Lapurdi","Baja Navarra","Zuberoa","Sin concretar"]},"uniqueItems":true}},{"name":"category","in":"query","style":"form","explode":true,"description":"Repeat this parameter to select multiple values","schema":{"type":"array","items":{"type":"string","enum":["Administración","Sanidad","Educación","Servicios"]},"uniqueItems":true}},{"name":"status","in":"query","style":"form","explode":true,"description":"Repeat this parameter to select multiple values","schema":{"type":"array","items":{"type":"string","enum":["Abierta","Próximamente","En curso","Cerrada","Calendario","Pendiente de confirmar"]},"uniqueItems":true}},{"name":"territory","in":"query","style":"form","explode":true,"description":"Repeat this parameter to select multiple values","schema":{"type":"array","items":{"type":"string","enum":["Euskadi","Navarra","País Vasco francés"]},"uniqueItems":true}},{"name":"source","in":"query","style":"form","explode":true,"description":"Repeat this parameter to select multiple values","schema":{"type":"array","items":{"type":"string","enum":["lanbide","vitoria","euskotren","euskadi","eitb","araba","donostia","ehu","ivap","osakidetza","navarra","cdg64"]},"uniqueItems":true}},{"name":"qualification","in":"query","style":"form","explode":true,"description":"Repeat this parameter to select multiple values","schema":{"type":"array","items":{"type":"string","enum":["eso","bachiller","fp-medio","fp-superior","grado","enfermeria","medicina","fisioterapia","farmacia","veterinaria","psicologia","trabajo-social","derecho","economia","ade","educacion-infantil","educacion-primaria","arquitectura","ingenieria-informatica","ingenieria-industrial","ingenieria-civil","ingenieria-telecomunicaciones","biologia","quimica","bac","licence"]},"uniqueItems":true}}],"responses":{"200":{"description":"Page of public employment calls","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"type":"object","required":["calls","pagination"],"properties":{"calls":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid parameters","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Catalogue temporarily unavailable","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/calls/{id}":{"get":{"operationId":"getCall","tags":["Calls"],"summary":"Get a full call, eligibility requirements, documents and syllabus","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$","maxLength":150}}],"responses":{"200":{"description":"Full call","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"type":"object","required":["call"],"properties":{"call":{"$ref":"#/components/schemas/Call"}}}}}},"404":{"description":"Call not found","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Catalogue temporarily unavailable","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sources":{"get":{"operationId":"listSources","tags":["Sources"],"summary":"List sources, coverage and update status","responses":{"200":{"description":"Sources with their latest public update report","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"type":"object","required":["sources"],"properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}}}}},"503":{"description":"Catalogue temporarily unavailable","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/options":{"get":{"operationId":"getOptions","tags":["Catalogs"],"summary":"Get available filter and qualification values","responses":{"200":{"description":"Stable filter values","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Options"}}}}}}},"/health":{"get":{"operationId":"getHealth","tags":["Service"],"summary":"Check service health and catalogue connectivity","responses":{"200":{"description":"Available","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"type":"object","required":["status","mode"],"properties":{"status":{"type":"string","const":"ok"},"mode":{"type":"string","enum":["demo","catalogue"]}}}}}},"503":{"description":"Unavailable","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","const":"unavailable"}}}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Service"],"summary":"Download this OpenAPI specification","responses":{"200":{"description":"OpenAPI 3.1 document","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"* — Public API without credentials"}},"content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"Call":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9-]+$"},"title":{"type":"string","minLength":1},"organization":{"type":"string","minLength":1},"territory":{"type":"string","enum":["Euskadi","Navarra","País Vasco francés"]},"province":{"default":null,"anyOf":[{"type":"string","enum":["Araba / Álava","Bizkaia","Gipuzkoa","Navarra","Lapurdi","Baja Navarra","Zuberoa"]},{"type":"null"}]},"location":{"type":"string","minLength":1},"category":{"type":"string","enum":["Administración","Sanidad","Educación","Servicios"]},"group":{"type":"string"},"places":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"acceptedQualifications":{"type":"array","items":{"type":"string","enum":["eso","bachiller","fp-medio","fp-superior","grado","enfermeria","medicina","fisioterapia","farmacia","veterinaria","psicologia","trabajo-social","derecho","economia","ade","educacion-infantil","educacion-primaria","arquitectura","ingenieria-informatica","ingenieria-industrial","ingenieria-civil","ingenieria-telecomunicaciones","biologia","quimica","bac","licence"]}},"educationText":{"type":"string","minLength":1},"language":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","enum":["euskera","francés"]},"level":{"type":"string","enum":["A1","A2","B1","B2","C1","C2"]}},"required":["name","level"],"additionalProperties":false},{"type":"null"}]},"deadline":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"status":{"type":"string","enum":["Abierta","Próximamente","Cerrada","En curso","Calendario","Pendiente de confirmar","Ejemplo"]},"description":{"type":"string","minLength":1},"requirements":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"sourceUrl":{"type":"string","format":"uri"},"syllabusUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"isDemo":{"type":"boolean"},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"scrapedAt":{"default":null,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"sourceId":{"default":null,"type":["string","null"]},"sourceHash":{"default":null,"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}]},"reviewStatus":{"default":"reviewed","type":"string","enum":["automatic","reviewed"]},"languageStatus":{"default":"known","type":"string","enum":["unknown","known"]},"documents":{"default":[],"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"kind":{"type":"string","enum":["bases","temario","guia","calendario"]},"checkedAt":{"default":null,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"sha256":{"default":null,"type":["string","null"]}},"required":["title","url","kind","checkedAt","sha256"],"additionalProperties":false}}},"required":["id","title","organization","territory","province","location","category","group","places","acceptedQualifications","educationText","language","deadline","status","description","requirements","topics","sourceUrl","syllabusUrl","isDemo","verifiedAt","scrapedAt","sourceId","sourceHash","reviewStatus","languageStatus","documents"],"additionalProperties":false},"Source":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"coverage":{"type":"string"},"report":{"anyOf":[{"type":"object","properties":{"last_success":{"type":["string","null"]},"status":{"type":"string"},"count":{"type":"number"},"attemptedAt":{"type":"string"},"warningCount":{"type":"number"}},"required":["last_success","status","count","attemptedAt","warningCount"],"additionalProperties":false},{"type":"null"}]}},"required":["id","name","url","coverage","report"],"additionalProperties":false},"Pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":1,"maximum":9007199254740991},"limit":{"type":"integer","minimum":1,"maximum":200},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"pages":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["page","limit","total","pages"],"additionalProperties":false},"Options":{"type":"object","properties":{"provinces":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"statuses":{"type":"array","items":{"type":"string"}},"territories":{"type":"array","items":{"type":"string"}},"qualifications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}},"required":["id","label"],"additionalProperties":false}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"sorts":{"type":"array","items":{"type":"string"}}},"required":["provinces","categories","statuses","territories","qualifications","sources","sorts"],"additionalProperties":false},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_QUERY","NOT_FOUND","UNAVAILABLE"]},"message":{"type":"string"}}}}}}}}