{"openapi":"3.0.3","info":{"title":"Goldilocks PC API","version":"1.0.0","description":"Versioned JSON API for Goldilocks PC catalogue data."},"servers":[{"url":"https://goldilockspc.uk"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/regions":{"get":{"summary":"List active regions","responses":{"200":{"description":"Active regions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Region"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/retailers":{"get":{"summary":"List retailers for the resolved region","parameters":[{"$ref":"#/components/parameters/RegionQuery"}],"responses":{"200":{"description":"Active retailers","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Retailer"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/taxonomies":{"get":{"summary":"List taxonomy filters and options","parameters":[{"$ref":"#/components/parameters/RegionQuery"}],"responses":{"200":{"description":"Taxonomy filters","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Taxonomy"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/listings":{"get":{"summary":"List visible listings","parameters":[{"$ref":"#/components/parameters/RegionQuery"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Case-insensitive name search."},{"name":"min_price","in":"query","schema":{"type":"number","format":"float"}},{"name":"max_price","in":"query","schema":{"type":"number","format":"float"}},{"name":"stock_status","in":"query","schema":{"type":"string","enum":["in_stock","pre_order","out_of_stock","unavailable"]}},{"name":"budget","in":"query","schema":{"type":"string"},"description":"Comma-separated budget option slugs."},{"name":"use_case","in":"query","schema":{"type":"string"},"description":"Comma-separated taxonomy option slugs."},{"name":"resolution","in":"query","schema":{"type":"string"},"description":"Comma-separated taxonomy option slugs."},{"name":"preferences","in":"query","schema":{"type":"string"},"description":"Comma-separated taxonomy option slugs."},{"name":"taxonomy_options","in":"query","schema":{"type":"string"},"description":"Comma-separated taxonomy option slugs."},{"name":"sort","in":"query","schema":{"type":"string","enum":["price_asc","price_desc"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Visible listings","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/listings/{id}":{"get":{"summary":"Fetch one visible listing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/RegionQuery"}],"responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"parameters":{"RegionQuery":{"name":"region","in":"query","schema":{"type":"string"},"description":"Region slug such as uk."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found"}}}},"RateLimited":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Region":{"type":"object","required":["slug","name","country_code","currency_code","locale","primary_host"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"country_code":{"type":"string"},"currency_code":{"type":"string"},"locale":{"type":"string"},"primary_host":{"type":"string","nullable":true}}},"Retailer":{"type":"object","required":["slug","name","homepage_url"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"homepage_url":{"type":"string","nullable":true}}},"Taxonomy":{"type":"object","required":["slug","name","cardinality","region_scoped","options"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"cardinality":{"type":"string","enum":["single","multiple"]},"region_scoped":{"type":"boolean"},"options":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomyOption"}}}},"TaxonomyOption":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true}}},"Listing":{"type":"object","required":["id","name","currency_code","stock_status","state","gallery_image_urls","outbound_url","retailer","components","taxonomies","updated_at"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"price":{"type":"string","nullable":true},"currency_code":{"type":"string"},"stock_status":{"type":"string","enum":["in_stock","pre_order","out_of_stock","unavailable"]},"state":{"type":"string","enum":["pending_review","active","inactive","archived"]},"image_url":{"type":"string","nullable":true},"gallery_image_urls":{"type":"array","items":{"type":"string"}},"outbound_url":{"type":"string"},"retailer":{"$ref":"#/components/schemas/ListingRetailer"},"components":{"type":"array","items":{"$ref":"#/components/schemas/ListingComponent"}},"taxonomies":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/ListingTaxonomyOption"}}},"updated_at":{"type":"string","format":"date-time"}}},"ListingRetailer":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"}}},"ListingComponent":{"type":"object","required":["role","name","slug","active"],"properties":{"role":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"active":{"type":"boolean"}}},"ListingTaxonomyOption":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"}}}}}}