{"openapi":"3.1.0","info":{"title":"Public Phonebook API","description":"Public facility contact data with source provenance. No API key is required.","version":"0.1.0"},"servers":[{"url":"/"}],"components":{},"paths":{"/api/catalog":{"get":{"operationId":"getCatalog","tags":["Directory"],"summary":"Get categories, regions, and the active dataset","responses":{"200":{"description":"Directory catalog","content":{"application/json":{"schema":{"type":"object","properties":{"snapshot":{"type":"string","pattern":"^[a-f0-9]{64}$"},"generatedAt":{"type":"string","minLength":1},"contacts":{"type":"integer","minimum":0,"maximum":9007199254740991},"phones":{"type":"integer","minimum":0,"maximum":9007199254740991},"sourceCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"enum":["medical","dental","pharmacy","municipal_office","prefectural_office","nursing_care","disability_support","library","museum","archive","nursery","kindergarten","certified_child_center","small_scale_childcare","workplace_childcare","unlicensed_childcare","university","junior_college","technical_college","consumer_affairs","labour_bureau","labour_inspection","labour_consultation","child_consultation","social_withdrawal_support","pension_office","pension_consultation","tax_office","legal_affairs","fire_brigade_office","police_consultation","employment_office","parent_employment_support","graduate_employment_support","youth_employment_support","foreign_employment_support","local_employment_support","agriculture_employment_support","relocation_employment_support"],"type":"string"},"label":{"type":"string","minLength":1},"contacts":{"type":"integer","minimum":0,"maximum":9007199254740991},"publisher":{"type":"string","minLength":1},"license":{"type":"string","minLength":1},"licenseUrl":{"type":"string","format":"uri"}},"required":["id","label","contacts","publisher","license","licenseUrl"],"additionalProperties":false}},"prefectures":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])$"},"name":{"type":"string","minLength":1},"contacts":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["code","name","contacts"],"additionalProperties":false}},"municipalities":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])[0-9]{3}$"},"prefectureCode":{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])$"},"name":{"type":"string","minLength":1}},"required":["code","prefectureCode","name"],"additionalProperties":false}}},"required":["snapshot","generatedAt","contacts","phones","sourceCount","categories","prefectures","municipalities"],"additionalProperties":false}}}},"400":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"404":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"409":{"description":"The dataset changed; restart without a cursor","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"503":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}}}}},"/api/contacts":{"get":{"operationId":"searchContacts","tags":["Contacts"],"summary":"Search facilities by name, telephone number, category, and region","description":"Exact names precede prefixes and substrings. Ties use normalized name and stable ID. Follow links.next until null. A cursor is bound to its query, limit, and dataset snapshot. Parameters must occur once; unknown parameters are rejected.","parameters":[{"name":"q","in":"query","example":"国立国会図書館","description":"Name substring or a complete Japanese telephone number. NFKC and case normalization. Maximum 512 UTF-8 bytes.","schema":{"type":"string","default":"","maxLength":512}},{"name":"prefecture","in":"query","description":"Two-digit JIS prefecture code","schema":{"type":"string","enum":["01","02","03","04","05","06","07","08","09","10","11","12","13","14","15","16","17","18","19","20","21","22","23","24","25","26","27","28","29","30","31","32","33","34","35","36","37","38","39","40","41","42","43","44","45","46","47"]}},{"name":"municipality","in":"query","description":"Five-digit municipality code from the catalog. Implies its prefecture. A conflicting prefecture is rejected.","schema":{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])[0-9]{3}$"}},{"name":"category","in":"query","schema":{"type":"string","enum":["medical","dental","pharmacy","municipal_office","prefectural_office","nursing_care","disability_support","library","museum","archive","nursery","kindergarten","certified_child_center","small_scale_childcare","workplace_childcare","unlicensed_childcare","university","junior_college","technical_college","consumer_affairs","labour_bureau","labour_inspection","labour_consultation","child_consultation","social_withdrawal_support","pension_office","pension_consultation","tax_office","legal_affairs","fire_brigade_office","police_consultation","employment_office","parent_employment_support","graduate_employment_support","youth_employment_support","foreign_employment_support","local_employment_support","agriculture_employment_support","relocation_employment_support"]}},{"name":"limit","in":"query","example":5,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},{"name":"cursor","in":"query","description":"Opaque continuation token. Prefer links.next; do not construct or modify tokens.","schema":{"type":"string","maxLength":4096}}],"responses":{"200":{"description":"A stable page of contacts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9:._-]+$"},"name":{"type":"string","minLength":1,"maxLength":512},"category":{"enum":["medical","dental","pharmacy","municipal_office","prefectural_office","nursing_care","disability_support","library","museum","archive","nursery","kindergarten","certified_child_center","small_scale_childcare","workplace_childcare","unlicensed_childcare","university","junior_college","technical_college","consumer_affairs","labour_bureau","labour_inspection","labour_consultation","child_consultation","social_withdrawal_support","pension_office","pension_consultation","tax_office","legal_affairs","fire_brigade_office","police_consultation","employment_office","parent_employment_support","graduate_employment_support","youth_employment_support","foreign_employment_support","local_employment_support","agriculture_employment_support","relocation_employment_support"],"type":"string"},"prefectureCode":{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])$"},"municipalityCode":{"anyOf":[{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])[0-9]{3}$"},{"type":"null"}]},"address":{"type":"string"},"phones":{"type":"array","items":{"type":"object","properties":{"display":{"type":"string","minLength":1},"e164":{"type":"string","pattern":"^\\+81[1-9][0-9]{8,9}$"}},"required":["display","e164"],"additionalProperties":false},"minItems":1},"website":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"sourceId":{"type":"string","minLength":1},"sourceRecordId":{"type":"string","minLength":1},"sourceUrls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1},"license":{"type":"string","minLength":1},"licenseUrl":{"type":"string","format":"uri"},"dataAsOf":{"type":"string"},"retrievedAt":{"type":"string","minLength":1},"phoneConfirmed":{"type":"boolean"},"phoneConfirmationUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["id","name","category","prefectureCode","municipalityCode","address","phones","website","sourceId","sourceRecordId","sourceUrls","license","licenseUrl","dataAsOf","retrievedAt","phoneConfirmed","phoneConfirmationUrl"],"additionalProperties":false}},"meta":{"type":"object","properties":{"snapshot":{"type":"string","pattern":"^[a-f0-9]{64}$"},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["snapshot","total","nextCursor"],"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"next":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["self","next"],"additionalProperties":false}},"required":["data","meta","links"],"additionalProperties":false}}}},"400":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"404":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"409":{"description":"The dataset changed; restart without a cursor","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"503":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}}}}},"/api/contact-groups":{"get":{"operationId":"searchContactGroups","tags":["Contacts"],"summary":"Preview matching contacts in every facility category","description":"Unfiltered categories each preview up to min(3, limit) contacts, ordered by their best name match. Group counts are exact. Follow each results.links.next through the flat contacts endpoint to retrieve all remaining matches. Category-selected searches return a regular page. A cursor requires a category. Query, limit, and dataset cursor bindings are unchanged.","parameters":[{"name":"q","in":"query","example":"国立国会図書館","description":"Name substring or a complete Japanese telephone number. NFKC and case normalization. Maximum 512 UTF-8 bytes.","schema":{"type":"string","default":"","maxLength":512}},{"name":"prefecture","in":"query","description":"Two-digit JIS prefecture code","schema":{"type":"string","enum":["01","02","03","04","05","06","07","08","09","10","11","12","13","14","15","16","17","18","19","20","21","22","23","24","25","26","27","28","29","30","31","32","33","34","35","36","37","38","39","40","41","42","43","44","45","46","47"]}},{"name":"municipality","in":"query","description":"Five-digit municipality code from the catalog. Implies its prefecture. A conflicting prefecture is rejected.","schema":{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])[0-9]{3}$"}},{"name":"category","in":"query","schema":{"type":"string","enum":["medical","dental","pharmacy","municipal_office","prefectural_office","nursing_care","disability_support","library","museum","archive","nursery","kindergarten","certified_child_center","small_scale_childcare","workplace_childcare","unlicensed_childcare","university","junior_college","technical_college","consumer_affairs","labour_bureau","labour_inspection","labour_consultation","child_consultation","social_withdrawal_support","pension_office","pension_consultation","tax_office","legal_affairs","fire_brigade_office","police_consultation","employment_office","parent_employment_support","graduate_employment_support","youth_employment_support","foreign_employment_support","local_employment_support","agriculture_employment_support","relocation_employment_support"]}},{"name":"limit","in":"query","example":5,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},{"name":"cursor","in":"query","description":"Opaque continuation token. Prefer links.next; do not construct or modify tokens.","schema":{"type":"string","maxLength":4096}}],"responses":{"200":{"description":"Disjoint category previews from one dataset snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"object","properties":{"category":{"enum":["medical","dental","pharmacy","municipal_office","prefectural_office","nursing_care","disability_support","library","museum","archive","nursery","kindergarten","certified_child_center","small_scale_childcare","workplace_childcare","unlicensed_childcare","university","junior_college","technical_college","consumer_affairs","labour_bureau","labour_inspection","labour_consultation","child_consultation","social_withdrawal_support","pension_office","pension_consultation","tax_office","legal_affairs","fire_brigade_office","police_consultation","employment_office","parent_employment_support","graduate_employment_support","youth_employment_support","foreign_employment_support","local_employment_support","agriculture_employment_support","relocation_employment_support"],"type":"string"},"results":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9:._-]+$"},"name":{"type":"string","minLength":1,"maxLength":512},"category":{"enum":["medical","dental","pharmacy","municipal_office","prefectural_office","nursing_care","disability_support","library","museum","archive","nursery","kindergarten","certified_child_center","small_scale_childcare","workplace_childcare","unlicensed_childcare","university","junior_college","technical_college","consumer_affairs","labour_bureau","labour_inspection","labour_consultation","child_consultation","social_withdrawal_support","pension_office","pension_consultation","tax_office","legal_affairs","fire_brigade_office","police_consultation","employment_office","parent_employment_support","graduate_employment_support","youth_employment_support","foreign_employment_support","local_employment_support","agriculture_employment_support","relocation_employment_support"],"type":"string"},"prefectureCode":{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])$"},"municipalityCode":{"anyOf":[{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])[0-9]{3}$"},{"type":"null"}]},"address":{"type":"string"},"phones":{"type":"array","items":{"type":"object","properties":{"display":{"type":"string","minLength":1},"e164":{"type":"string","pattern":"^\\+81[1-9][0-9]{8,9}$"}},"required":["display","e164"],"additionalProperties":false},"minItems":1},"website":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"sourceId":{"type":"string","minLength":1},"sourceRecordId":{"type":"string","minLength":1},"sourceUrls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1},"license":{"type":"string","minLength":1},"licenseUrl":{"type":"string","format":"uri"},"dataAsOf":{"type":"string"},"retrievedAt":{"type":"string","minLength":1},"phoneConfirmed":{"type":"boolean"},"phoneConfirmationUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["id","name","category","prefectureCode","municipalityCode","address","phones","website","sourceId","sourceRecordId","sourceUrls","license","licenseUrl","dataAsOf","retrievedAt","phoneConfirmed","phoneConfirmationUrl"],"additionalProperties":false}},"meta":{"type":"object","properties":{"snapshot":{"type":"string","pattern":"^[a-f0-9]{64}$"},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["snapshot","total","nextCursor"],"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"next":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["self","next"],"additionalProperties":false}},"required":["data","meta","links"],"additionalProperties":false}},"required":["category","results"],"additionalProperties":false}},"meta":{"type":"object","properties":{"snapshot":{"type":"string","pattern":"^[a-f0-9]{64}$"},"total":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["snapshot","total"],"additionalProperties":false}},"required":["groups","meta"],"additionalProperties":false}}}},"400":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"404":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"409":{"description":"The dataset changed; restart without a cursor","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"503":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}}}}},"/api/contacts/{id}":{"get":{"operationId":"getContact","tags":["Contacts"],"summary":"Get a facility and its provenance","responses":{"200":{"description":"Contact","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9:._-]+$"},"name":{"type":"string","minLength":1,"maxLength":512},"category":{"enum":["medical","dental","pharmacy","municipal_office","prefectural_office","nursing_care","disability_support","library","museum","archive","nursery","kindergarten","certified_child_center","small_scale_childcare","workplace_childcare","unlicensed_childcare","university","junior_college","technical_college","consumer_affairs","labour_bureau","labour_inspection","labour_consultation","child_consultation","social_withdrawal_support","pension_office","pension_consultation","tax_office","legal_affairs","fire_brigade_office","police_consultation","employment_office","parent_employment_support","graduate_employment_support","youth_employment_support","foreign_employment_support","local_employment_support","agriculture_employment_support","relocation_employment_support"],"type":"string"},"prefectureCode":{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])$"},"municipalityCode":{"anyOf":[{"type":"string","pattern":"^(0[1-9]|[1-3][0-9]|4[0-7])[0-9]{3}$"},{"type":"null"}]},"address":{"type":"string"},"phones":{"type":"array","items":{"type":"object","properties":{"display":{"type":"string","minLength":1},"e164":{"type":"string","pattern":"^\\+81[1-9][0-9]{8,9}$"}},"required":["display","e164"],"additionalProperties":false},"minItems":1},"website":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"sourceId":{"type":"string","minLength":1},"sourceRecordId":{"type":"string","minLength":1},"sourceUrls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1},"license":{"type":"string","minLength":1},"licenseUrl":{"type":"string","format":"uri"},"dataAsOf":{"type":"string"},"retrievedAt":{"type":"string","minLength":1},"phoneConfirmed":{"type":"boolean"},"phoneConfirmationUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["id","name","category","prefectureCode","municipalityCode","address","phones","website","sourceId","sourceRecordId","sourceUrls","license","licenseUrl","dataAsOf","retrievedAt","phoneConfirmed","phoneConfirmationUrl"],"additionalProperties":false}}}},"400":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"404":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"409":{"description":"The dataset changed; restart without a cursor","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"503":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/api/contacts/{id}/contact.vcf":{"get":{"operationId":"downloadContact","tags":["Contacts"],"summary":"Download one complete vCard","responses":{"200":{"description":"vCard 3.0, UTF-8, CRLF, 75-byte folded lines","content":{"text/vcard":{"schema":{"type":"string"}}}},"400":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"404":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"409":{"description":"The dataset changed; restart without a cursor","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"503":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/api/sources":{"get":{"operationId":"listSources","tags":["Sources"],"summary":"List source provenance and import results","responses":{"200":{"description":"Sources","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"dataAsOf":{"type":"string"},"retrievedAt":{"type":"string","minLength":1},"indexUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"indexSha256":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}]},"licenseUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"licenseSha256":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}]},"artifacts":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"retrievedAt":{"type":"string","minLength":1}},"required":["url","sha256","retrievedAt"],"additionalProperties":false}},"rows":{"type":"integer","minimum":0,"maximum":9007199254740991},"accepted":{"type":"integer","minimum":0,"maximum":9007199254740991},"missingPhone":{"type":"integer","minimum":0,"maximum":9007199254740991},"invalid":{"type":"integer","minimum":0,"maximum":9007199254740991},"duplicate":{"type":"integer","minimum":0,"maximum":9007199254740991},"issues":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"required":["id","url","sha256","dataAsOf","retrievedAt","indexUrl","indexSha256","licenseUrl","licenseSha256","artifacts","rows","accepted","missingPhone","invalid","duplicate","issues"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"404":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"409":{"description":"The dataset changed; restart without a cursor","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"503":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}}}}},"/api/sources/{id}":{"get":{"operationId":"getSource","tags":["Sources"],"summary":"Get source archive hashes and import counts","responses":{"200":{"description":"Source","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"dataAsOf":{"type":"string"},"retrievedAt":{"type":"string","minLength":1},"indexUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"indexSha256":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}]},"licenseUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"licenseSha256":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}]},"artifacts":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"retrievedAt":{"type":"string","minLength":1}},"required":["url","sha256","retrievedAt"],"additionalProperties":false}},"rows":{"type":"integer","minimum":0,"maximum":9007199254740991},"accepted":{"type":"integer","minimum":0,"maximum":9007199254740991},"missingPhone":{"type":"integer","minimum":0,"maximum":9007199254740991},"invalid":{"type":"integer","minimum":0,"maximum":9007199254740991},"duplicate":{"type":"integer","minimum":0,"maximum":9007199254740991},"issues":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"required":["id","url","sha256","dataAsOf","retrievedAt","indexUrl","indexSha256","licenseUrl","licenseSha256","artifacts","rows","accepted","missingPhone","invalid","duplicate","issues"],"additionalProperties":false}}}},"400":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"404":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"409":{"description":"The dataset changed; restart without a cursor","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"503":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/api/datasets":{"get":{"operationId":"getDatasetManifest","tags":["Datasets"],"summary":"Get complete dataset download URLs, byte lengths, and SHA-256 hashes","responses":{"200":{"description":"Current snapshot manifest","content":{"application/json":{"schema":{"type":"object","properties":{"snapshot":{"type":"string","pattern":"^[a-f0-9]{64}$"},"generatedAt":{"type":"string","minLength":1},"contacts":{"type":"integer","minimum":0,"maximum":9007199254740991},"phones":{"type":"integer","minimum":0,"maximum":9007199254740991},"sourceCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"sourceDatabaseSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"databaseSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"files":{"type":"array","items":{"type":"object","properties":{"file":{"enum":["contacts.jsonl.gz","contacts.csv.gz","contacts.vcf.gz"],"type":"string"},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"bytes":{"type":"integer","minimum":0,"maximum":9007199254740991},"url":{"type":"string"}},"required":["file","sha256","bytes","url"],"additionalProperties":false},"minItems":3,"maxItems":3}},"required":["snapshot","generatedAt","contacts","phones","sourceCount","sourceDatabaseSha256","databaseSha256","files"],"additionalProperties":false}}}},"400":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"404":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"409":{"description":"The dataset changed; restart without a cursor","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"503":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}}}}},"/api/datasets/{snapshot}/{digest}/{file}":{"get":{"operationId":"downloadDataset","tags":["Datasets"],"summary":"Download immutable complete JSONL, CSV, or vCard data","responses":{"200":{"description":"Gzip archive with immutable caching and an ETag"},"400":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"404":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"409":{"description":"The dataset changed; restart without a cursor","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}},"503":{"description":"An RFC 9457 problem with a request ID","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"code":{"enum":["invalid_query","conflicting_region","invalid_cursor","snapshot_changed","not_found","method_not_allowed","unavailable"],"type":"string"},"requestId":{"type":"string"}},"required":["type","title","status","code","requestId"],"additionalProperties":false}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"snapshot","required":true},{"schema":{"type":"string"},"in":"path","name":"digest","required":true},{"schema":{"type":"string"},"in":"path","name":"file","required":true}]}}}}