{"openapi":"3.0.3","info":{"title":"directory.lgbt Public API","version":"1.0","description":"Read-only, versioned, keyless JSON API over the same published-listings read surface the site itself uses. Search results are NOT synonym-expanded or typo-tolerant (that lives in the on-site search box only, via Meilisearch, Phase 33) — this is a deliberate, documented divergence between the machine surface and the human surface, not a bug.","termsOfService":"/api-usage-terms"},"paths":{"/api/v1":{"get":{"tags":["meta"],"summary":"API root","description":"Self-describing links to the spec, docs UI, usage terms, and every resource.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"links":{"type":"object","properties":{"openapi":{"type":"string"},"docs":{"type":"string"},"terms":{"type":"string"},"listings":{"type":"string"},"organisations":{"type":"string"},"categories":{"type":"string"}},"required":["openapi","docs","terms","listings","organisations","categories"],"additionalProperties":false}},"required":["name","version","description","links"],"additionalProperties":false}}}}}}},"/api/v1/listings":{"get":{"tags":["listings"],"summary":"Search published listings","description":"The same masked read surface as the site. Search results are NOT synonym-expanded or typo-tolerant (that is on-site-only, via Meilisearch); see /api-usage-terms for details.","parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"lat","schema":{"type":"number"}},{"in":"query","name":"lng","schema":{"type":"number"}},{"in":"query","name":"radius","schema":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":100}},{"in":"query","name":"category","schema":{"type":"array","items":{"type":"string"}}},{"in":"query","name":"identity","schema":{"type":"array","items":{"type":"string"}}},{"in":"query","name":"accessibility","schema":{"type":"array","items":{"type":"string"}}},{"in":"query","name":"region","schema":{"type":"string"}},{"in":"query","name":"sort","schema":{"type":"string","enum":["relevance","distance","name"],"default":"relevance"}},{"in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"in":"query","name":"include_adult","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"slug":{"type":"string"},"short_id":{"type":"string","description":"Stable 8-character listing identifier, immutable even when the listing is renamed. Build the canonical web URL as /listings/{slug}-{short_id} (see /api-usage-terms)."},"short_description":{"nullable":true,"type":"string"},"category_name":{"type":"string"},"category_slug":{"type":"string"},"delivery_mode":{"type":"string","enum":["in_person","online","phone","hybrid"]},"distance_miles":{"nullable":true,"type":"number"},"town_city":{"nullable":true,"type":"string"},"county":{"nullable":true,"type":"string"},"visibility_tier":{"nullable":true,"type":"string","enum":["full_address","area_only","online_only"]},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"tag_type":{"type":"string","enum":["identity","accessibility","feature"]}},"required":["name","slug","tag_type"],"additionalProperties":false}},"relevance_score":{"nullable":true,"type":"number"},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"matched_via_aka":{"type":"boolean"},"matched_aka":{"nullable":true,"type":"string"}},"required":["id","name","slug","short_id","short_description","category_name","category_slug","delivery_mode","distance_miles","town_city","county","visibility_tier","tags","relevance_score","latitude","longitude","matched_via_aka","matched_aka"],"additionalProperties":false}},"meta":{"type":"object","properties":{"total":{"type":"number"},"facets":{"type":"object","properties":{"category":{"type":"object","additionalProperties":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"count":{"type":"number"},"disabled":{"type":"boolean"}},"required":["slug","label","count","disabled"],"additionalProperties":false}},"identity":{"type":"object","additionalProperties":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"count":{"type":"number"},"disabled":{"type":"boolean"}},"required":["slug","label","count","disabled"],"additionalProperties":false}},"accessibility":{"type":"object","additionalProperties":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"count":{"type":"number"},"disabled":{"type":"boolean"}},"required":["slug","label","count","disabled"],"additionalProperties":false}}},"required":["category","identity","accessibility"],"additionalProperties":false}},"required":["total","facets"],"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"},"next":{"nullable":true,"type":"string"}},"required":["self","next"],"additionalProperties":false}},"required":["data","meta","links"],"additionalProperties":false}}}},"400":{"description":"Invalid query parameters"},"502":{"description":"Upstream read failed"}}}},"/api/v1/listings/{id}":{"get":{"tags":["listings"],"summary":"Fetch a single published listing","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"query","name":"include_adult","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"slug":{"type":"string"},"short_id":{"type":"string","description":"Stable 8-character listing identifier, immutable even when the listing is renamed. Build the canonical web URL as /listings/{slug}-{short_id} (see /api-usage-terms)."},"short_description":{"nullable":true,"type":"string"},"long_description":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"email":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"social_links":{"nullable":true,"type":"object","additionalProperties":{"type":"string"}},"opening_hours":{"nullable":true,"type":"array","items":{"type":"object","properties":{"day":{"anyOf":[{"type":"string"},{"type":"number"}]},"open":{"type":"string"},"close":{"type":"string"},"closed":{"type":"boolean"}},"required":["day"],"additionalProperties":false}},"content_rating":{"type":"string"},"delivery_mode":{"type":"string","enum":["in_person","online","phone","hybrid"]},"human_verified_at":{"nullable":true,"description":"ISO timestamp a human reviewer confirmed this listing (D-32), or null if not yet human-verified. A positive-only trust signal — a null value means \"not yet reviewed\", never a negative marker.","type":"string"},"category":{"nullable":true,"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"nullable":true,"type":"string"},"icon":{"nullable":true,"type":"string"}},"required":["id","name","slug","description","icon"],"additionalProperties":false},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"tag_type":{"type":"string","enum":["identity","accessibility","feature"]}},"required":["name","slug","tag_type"],"additionalProperties":false}},"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"label":{"nullable":true,"type":"string"},"is_primary":{"type":"boolean"},"location_type":{"nullable":true,"type":"string"},"address_line_1":{"nullable":true,"type":"string"},"address_line_2":{"nullable":true,"type":"string"},"town_city":{"nullable":true,"type":"string"},"county":{"nullable":true,"type":"string"},"postcode":{"nullable":true,"type":"string"},"country":{"type":"string"},"visibility_tier":{"type":"string","enum":["full_address","area_only","online_only"]}},"required":["id","label","is_primary","location_type","address_line_1","address_line_2","town_city","county","postcode","country","visibility_tier"],"additionalProperties":false}},"organisation":{"nullable":true,"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"logo_url":{"nullable":true,"type":"string"}},"required":["id","name","logo_url"],"additionalProperties":false}},"required":["id","name","slug","short_id","short_description","long_description","phone","email","website","social_links","opening_hours","content_rating","delivery_mode","human_verified_at","category","tags","locations","organisation"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Invalid id or query parameters"},"404":{"description":"Not found or not public (also returned for an adult-rated listing when include_adult is not set)"},"502":{"description":"Upstream read failed"}}}},"/api/v1/organisations/{id}":{"get":{"tags":["organisations"],"summary":"Fetch a single published organisation","description":"Masked per visibility tier per address.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"query","name":"include_adult","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"nullable":true,"type":"string"},"logo_url":{"nullable":true,"type":"string"},"charity_number":{"nullable":true,"type":"string"},"company_number":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"email":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"socials":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"url":{"type":"string"}},"required":["platform","url"],"additionalProperties":false}},"concepts":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"dimension":{"type":"string","enum":["category","tag"]}},"required":["slug","label","dimension"],"additionalProperties":false}},"addresses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"role":{"type":"string","enum":["registered","contact","operating"]},"address_line_1":{"nullable":true,"type":"string"},"address_line_2":{"nullable":true,"type":"string"},"town_city":{"nullable":true,"type":"string"},"county":{"nullable":true,"type":"string"},"postcode":{"nullable":true,"type":"string"},"country":{"type":"string"},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"visibility_tier":{"type":"string","enum":["full_address","area_only","online_only"]}},"required":["id","role","address_line_1","address_line_2","town_city","county","postcode","country","latitude","longitude","visibility_tier"],"additionalProperties":false}}},"required":["id","name","slug","description","logo_url","charity_number","company_number","website","email","phone","socials","concepts","addresses"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Invalid id or query parameters"},"404":{"description":"Not found or not public (also returned when every listing for this organisation is adult-rated and include_adult is not set)"},"502":{"description":"Upstream read failed"}}}},"/api/v1/categories":{"get":{"tags":["categories"],"summary":"The public category taxonomy","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"nullable":true,"type":"string"},"icon":{"nullable":true,"type":"string"}},"required":["id","name","slug","description","icon"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"502":{"description":"Upstream read failed"}}}}}}