{"openapi":"3.1.0","info":{"title":"PegeGrid Public Sample API","version":"1.0.0","description":"Bounded, publication-cleared sample of Miami-Dade recording studios. Only public REST routes are described here."},"servers":[{"url":"https://pegegrid.com"}],"paths":{"/v1/sample/entities":{"get":{"operationId":"sampleEntities","summary":"Search the public studio sample","description":"Filters inspect published facts only. The sample contains active studios with at least probable confidence and a publishable name. Results are capped at five per page and two pages per query; page offsets use a fixed stride of five.","parameters":[{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Service"},{"$ref":"#/components/parameters/RoomType"},{"$ref":"#/components/parameters/EquipmentCategory"},{"$ref":"#/components/parameters/HasPricing"},{"$ref":"#/components/parameters/HasRooms"},{"$ref":"#/components/parameters/HasWebsite"},{"$ref":"#/components/parameters/MaxHourlyRate"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Page"}],"responses":{"200":{"description":"Public records and query metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"$ref":"#/components/responses/AuthenticatedAccessRequired"},"422":{"$ref":"#/components/responses/InvalidParameter"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/sample/entities/{id}":{"get":{"operationId":"sampleEntity","summary":"Get one record in the public sample","parameters":[{"name":"id","in":"path","required":true,"description":"entity_id returned by the public search","schema":{"type":"string"}}],"responses":{"200":{"description":"One public studio record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityResponse"}}}},"401":{"$ref":"#/components/responses/AuthenticatedAccessRequired"},"404":{"description":"Entity does not exist in the public sample"},"422":{"$ref":"#/components/responses/InvalidParameter"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/sample/meta":{"get":{"operationId":"sampleMeta","summary":"Get current public release metadata","responses":{"200":{"description":"Release, freshness, population, facets, and access policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"parameters":{"City":{"name":"city","in":"query","schema":{"type":"string"},"description":"Exact city name, case-insensitive"},"Service":{"name":"service","in":"query","schema":{"type":"string"},"description":"Published canonical service term"},"RoomType":{"name":"room_type","in":"query","schema":{"type":"string"},"description":"Published room type"},"EquipmentCategory":{"name":"equipment_category","in":"query","schema":{"type":"string"},"description":"Published equipment category"},"HasPricing":{"name":"has_pricing","in":"query","schema":{"type":"boolean"},"description":"Whether public pricing exists"},"HasRooms":{"name":"has_rooms","in":"query","schema":{"type":"boolean"},"description":"Whether public room information exists"},"HasWebsite":{"name":"has_website","in":"query","schema":{"type":"boolean"},"description":"Whether a publishable website exists"},"MaxHourlyRate":{"name":"max_hourly_rate","in":"query","schema":{"type":"number"},"description":"Maximum published minimum hourly USD price"},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":5,"default":5}},"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":2,"default":1}}},"responses":{"AuthenticatedAccessRequired":{"description":"Requested capability is outside the public sample","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessBoundary"}}}},"InvalidParameter":{"description":"Invalid public query parameter"},"RateLimited":{"description":"Public rate limit reached"}},"schemas":{"AccessBoundary":{"type":"object","required":["error","message","capability","auth_required"],"properties":{"error":{"const":"authenticated_access_required"},"message":{"type":"string"},"capability":{"type":"string","enum":["larger_result_sets","pagination","free_text_search","full_view","protected_fields","low_confidence_records","closed_records","geo_search","advanced_filters","change_feed"]},"auth_required":{"const":true},"authenticated_access":{"type":"object"}}},"Studio":{"type":"object","description":"Only publication-cleared facts are present. Empty arrays or null values mean the category has no public value, not necessarily that the studio lacks it.","required":["entity_id","name","confidence_tier","operating_status","location","website","services","capabilities","rooms","equipment","pricing","withheld","release_id","freshness","provenance","attribution"],"properties":{"entity_id":{"type":"string"},"name":{"type":"string"},"confidence_tier":{"type":"string","enum":["confirmed","probable"]},"operating_status":{"type":["string","null"]},"location":{"type":"object","properties":{"city":{"type":["string","null"]},"state":{"type":["string","null"]},"postal_code":{"type":["string","null"]}}},"website":{"type":["object","null"],"description":"Published URL plus association status, or null","properties":{"url":{"type":"string","format":"uri"},"association":{"type":["string","null"]}}},"services":{"type":"array","items":{"type":"string"}},"capabilities":{"type":"array","items":{"type":"string"}},"rooms":{"type":"array","items":{"type":"object","additionalProperties":true}},"equipment":{"type":"array","items":{"type":"object","additionalProperties":true}},"pricing":{"type":"array","items":{"type":"object","additionalProperties":true}},"withheld":{"type":"array","description":"Names of categories with unpublished facts; no values","items":{"type":"string"}},"release_id":{"type":"string"},"freshness":{"type":"object","properties":{"record_observed_at":{"type":["string","null"]},"record_last_verified_at":{"type":["string","null"]},"release_generated_at":{"type":"string"}}},"provenance":{"type":"object","description":"Aggregate counts only; no field-level provenance","properties":{"published_source_count":{"type":"integer"},"published_sources_by_kind":{"type":"object","additionalProperties":{"type":"integer"}}}},"attribution":{"type":"object"}}},"SearchResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/Studio"}},"meta":{"type":"object","required":["release_id","dataset_generated_at","count","total_matches","limit","page","pages_max","results_capped","next_page","access"],"properties":{"release_id":{"type":"string"},"dataset_generated_at":{"type":"string"},"count":{"type":"integer"},"total_matches":{"type":"integer"},"limit":{"type":"integer","maximum":5},"page":{"type":"integer","maximum":2},"pages_max":{"const":2},"results_capped":{"type":"boolean"},"next_page":{"type":["integer","null"]},"access":{"$ref":"#/components/schemas/Access"}}}}},"EntityResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Studio"},"meta":{"type":"object","properties":{"release_id":{"type":"string"},"dataset_generated_at":{"type":"string"},"access":{"$ref":"#/components/schemas/Access"}}}}},"MetaResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["release_id","vertical","geography","dataset_generated_at","schema_version","sample_population","facets","access"],"properties":{"release_id":{"type":"string"},"vertical":{"type":"string"},"geography":{"type":"string"},"dataset_generated_at":{"type":"string"},"schema_version":{"type":"string"},"sample_population":{"type":"object","properties":{"records":{"type":"integer"},"rule":{"type":"string"}}},"facets":{"type":"object"},"access":{"$ref":"#/components/schemas/Access"}}},"meta":{"type":"object","properties":{"release_id":{"type":"string"},"dataset_generated_at":{"type":"string"}}}}},"Access":{"type":"object","description":"Public sample limits, population rule, field policy, and authenticated-access capability names","properties":{"surface":{"const":"public_sample"},"limits":{"type":"object","properties":{"page_size_max":{"const":5},"pages_max":{"const":2},"results_per_query_max":{"const":10},"pagination_cursor":{"const":false}}},"population":{"type":"string"},"field_policy":{"type":"string"},"authenticated_access":{"type":"object"}}}}}}