{"openapi":"3.1.0","info":{"title":"Israeli Doctors Database","version":"3.0.0","description":"Free read-only registry-based physician profiles. Dated snapshots, independently rule-assessed enrichment, clinic geography, editorial prominence. No API key. Migration notes: /updates."},"servers":[{"url":"/"}],"security":[],"paths":{"/api/v1/search":{"get":{"operationId":"search","description":"One result per registry identity, not separate source records","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":120,"minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SearchPage"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/fetch":{"get":{"operationId":"fetch","description":"Fetch doctor:{licence} or an accepted legacy alias","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","maxLength":240}}],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Record"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/find":{"get":{"operationId":"find_doctors","description":"Certified specialty and clinic-city filters on canonical profiles. Hospital location never supplies clinic geography.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"specialty","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"city","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"region","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"hospital","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"hospital_employed","in":"query","required":false,"schema":{"type":"boolean","description":"Whether the profile has an accepted hospital staff listing; not a claim of current employment."}},{"name":"certified_only","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctorPage"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/recommendations":{"get":{"operationId":"recommend_doctors","description":"Editorial prominence within covered profiles, not clinical quality","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"specialty","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"city","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"region","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"hospital","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"hospital_employed","in":"query","required":false,"schema":{"type":"boolean","description":"Whether the profile has an accepted hospital staff listing; not a claim of current employment."}},{"name":"certified_only","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoctorPage"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/compare":{"get":{"operationId":"compare_doctors","description":"Factual comparison of 2–4 different canonical identities","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated doctor:{licence} IDs"}}],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Object"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/registry/check-specialty":{"get":{"operationId":"check_registered_specialty","description":"Resolve an exact name or licence before testing certified specialty; ambiguous names remain ambiguous","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":120}},{"name":"specialty","in":"query","required":true,"schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Object"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/specialty-catalog":{"get":{"operationId":"specialty_catalog","description":"Read specialty-catalog","parameters":[],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Object"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/city-catalog":{"get":{"operationId":"city_catalog","description":"Read city-catalog","parameters":[],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Object"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/data-catalog":{"get":{"operationId":"data_catalog","description":"Read data-catalog","parameters":[],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Object"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/methodology":{"get":{"operationId":"methodology","description":"Read methodology","parameters":[],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Object"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/regions":{"get":{"operationId":"regions","description":"Read regions","parameters":[],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Object"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/page":{"get":{"operationId":"page_data","description":"Structured representation of a canonical local page","parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string","maxLength":600}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"Read-only response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Object"}}}]}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mcp":{"post":{"operationId":"mcpJsonRpc","summary":"Read-only MCP Streamable HTTP endpoint","description":"Send JSON-RPC 2.0 initialize, tools/list, tools/call or ping. Provide Accept: application/json, text/event-stream. No authentication; nine read-only tools.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["integer","string"]},"method":{"type":"string"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Notification accepted"}}}}},"components":{"schemas":{"Object":{"type":"object","additionalProperties":true},"Doctor":{"type":"object","required":["id","licence_number","name","url","certified_specialties","locations","hospitals","snapshot_date"],"properties":{"id":{"type":"string","pattern":"^doctor:[0-9]+$"},"licence_number":{"type":"string"},"name":{"type":"string"},"first_name":{"type":["string","null"]},"surname":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"licence_registered_on":{"type":["string","null"],"format":"date"},"licence_year":{"type":["integer","null"]},"certified_specialties":{"type":"array","items":{"type":"string"}},"specialty_registrations":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"certificate_number":{"type":["string","number","null"]},"registered_on":{"type":["string","null"]}}}},"licence_status":{"type":["object","null"],"description":"Separately dated status observation, never assumed live"},"practice_expertise":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string"},"region":{"type":["string","null"]},"region_id":{"type":["string","null"]},"basis":{"type":"string"}}}},"hospitals":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":["string","null"]},"department":{"type":["string","null"]},"source_url":{"type":"string"},"evidence":{"type":"object","additionalProperties":true}}}},"enrichment_links":{"type":"array","items":{"type":"object","additionalProperties":true}},"recognition":{"type":"array","items":{"type":"object","additionalProperties":true}},"featured":{"type":"boolean"},"editorial_score":{"type":["integer","null"]},"clinical_quality_score":{"type":"null"},"snapshot_date":{"type":"string","format":"date"}}},"Record":{"type":"object","properties":{"id":{"type":"string"},"record_type":{"const":"doctor"},"url":{"type":"string"},"data":{"$ref":"#/components/schemas/Doctor"}}},"DoctorPage":{"type":"object","required":["total","offset","limit","results"],"properties":{"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Doctor"}}}},"SearchPage":{"type":"object","properties":{"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"json_url":{"type":"string"},"markdown_url":{"type":"string"}}}}}},"Envelope":{"type":"object","required":["apiVersion","data","links","meta"],"properties":{"apiVersion":{"const":"3.0.0"},"documentationUpdated":{"type":"string"},"data":{"type":"object","additionalProperties":true},"links":{"type":"object","additionalProperties":true},"meta":{"type":"object","additionalProperties":true}}},"Error":{"type":"object","required":["error"],"properties":{"apiVersion":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}