{"openapi":"3.1.0","info":{"title":"All Paint Colours API","description":"Every paint colour from every major UK manufacturer — cross-brand CIEDE2000 matching, prices, finish specs, palettes, planner projects, and market data.\n\n**Auth**: `Authorization: Bearer <api key>` — create keys at [allpaintcolours.co.uk/account](https://allpaintcolours.co.uk/account/). Tiers: Free (colour research and comparison — price fields locked), Home £12/mo (everything with a £ sign: full price data, cheapest-alternative analysis, planner projects), Pro £60/mo (what the market wants: trends, rankings, range and price changes, bulk export). Prices include UK VAT. Full details: [allpaintcolours.co.uk/pricing](https://allpaintcolours.co.uk/pricing/). Also available as an MCP server: `https://mcp.allpaintcolours.co.uk/mcp`.","version":"2.0"},"servers":[{"url":"/api/v2"},{"url":"https://allpaintcolours.co.uk/api/v2"}],"paths":{"/search":{"get":{"summary":"Search","operationId":"search_search_get","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","title":"Query"}},{"name":"manufacturer","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Manufacturer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/colour/{manufacturer}/{colour}":{"get":{"summary":"Colour Detail","operationId":"colour_detail_colour__manufacturer___colour__get","parameters":[{"name":"manufacturer","in":"path","required":true,"schema":{"type":"string","title":"Manufacturer"}},{"name":"colour","in":"path","required":true,"schema":{"type":"string","title":"Colour"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/match":{"post":{"summary":"Match","operationId":"match_match_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/manufacturers":{"get":{"summary":"Manufacturers","operationId":"manufacturers_manufacturers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/finishes":{"get":{"summary":"Finishes","operationId":"finishes_finishes_get","parameters":[{"name":"manufacturer","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Manufacturer"}},{"name":"include_primers","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Include Primers"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cheapest-alternative/{manufacturer}/{colour}":{"get":{"summary":"Cheapest","operationId":"cheapest_cheapest_alternative__manufacturer___colour__get","parameters":[{"name":"manufacturer","in":"path","required":true,"schema":{"type":"string","title":"Manufacturer"}},{"name":"colour","in":"path","required":true,"schema":{"type":"string","title":"Colour"}},{"name":"max_delta_e","in":"query","required":false,"schema":{"type":"number","default":3.0,"title":"Max Delta E"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10,"default":5,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/trends":{"get":{"summary":"Trends","operationId":"trends_trends_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period"}},{"name":"colour_family","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Colour Family"}},{"name":"manufacturer","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Manufacturer"}},{"name":"metric","in":"query","required":false,"schema":{"type":"string","default":"combined","title":"Metric"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"default":15,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/trends/{manufacturer}/{colour}":{"get":{"summary":"Colour Trend","operationId":"colour_trend_trends__manufacturer___colour__get","parameters":[{"name":"manufacturer","in":"path","required":true,"schema":{"type":"string","title":"Manufacturer"}},{"name":"colour","in":"path","required":true,"schema":{"type":"string","title":"Colour"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rankings":{"get":{"summary":"Rankings","operationId":"rankings_rankings_get","parameters":[{"name":"metric","in":"query","required":true,"schema":{"type":"string","title":"Metric"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"default":15,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/changes":{"get":{"summary":"Changes","operationId":"changes_changes_get","parameters":[{"name":"change_type","in":"query","required":true,"schema":{"type":"string","title":"Change Type"}},{"name":"manufacturer","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Manufacturer"}},{"name":"months","in":"query","required":false,"schema":{"type":"integer","maximum":24,"default":3,"title":"Months"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"default":30,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/palettes":{"get":{"summary":"Palettes List","operationId":"palettes_list_palettes_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Palettes Save","operationId":"palettes_save_palettes_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaletteIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/palettes/{ident}":{"get":{"summary":"Palettes Get","operationId":"palettes_get_palettes__ident__get","parameters":[{"name":"ident","in":"path","required":true,"schema":{"type":"string","title":"Ident"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/planner-projects":{"get":{"summary":"Projects List","operationId":"projects_list_planner_projects_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Projects Save","operationId":"projects_save_planner_projects_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/planner-projects/{ident}":{"get":{"summary":"Projects Get","operationId":"projects_get_planner_projects__ident__get","parameters":[{"name":"ident","in":"path","required":true,"schema":{"type":"string","title":"Ident"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ColourRef":{"properties":{"manufacturer":{"type":"string","title":"Manufacturer","description":"Brand name or slug, e.g. 'Farrow & Ball'"},"colour":{"type":"string","title":"Colour","description":"Colour name, slug, or number, e.g. 'Railings'"}},"type":"object","required":["manufacturer","colour"],"title":"ColourRef"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MatchRequest":{"properties":{"colours":{"items":{"type":"string"},"type":"array","title":"Colours","description":"Hex values, e.g. [\"#434548\"]. Max 20."},"manufacturers":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Manufacturers"},"include_standards":{"type":"boolean","title":"Include Standards","default":false},"max_delta_e":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Delta E"},"limit":{"type":"integer","title":"Limit","default":5}},"type":"object","required":["colours"],"title":"MatchRequest"},"PaletteIn":{"properties":{"name":{"type":"string","title":"Name"},"colours":{"items":{"$ref":"#/components/schemas/ColourRef"},"type":"array","title":"Colours"}},"type":"object","required":["name","colours"],"title":"PaletteIn"},"ProjectIn":{"properties":{"name":{"type":"string","title":"Name"},"rooms":{"items":{"$ref":"#/components/schemas/RoomSpec"},"type":"array","title":"Rooms"}},"type":"object","required":["name","rooms"],"title":"ProjectIn"},"RoomSpec":{"properties":{"name":{"type":"string","title":"Name","description":"Room name, e.g. 'Bedroom'"},"length_m":{"type":"number","title":"Length M","description":"Room length in metres (0.5–30)"},"width_m":{"type":"number","title":"Width M","description":"Room width in metres (0.5–30)"},"height_m":{"type":"number","title":"Height M","description":"Ceiling height in metres","default":2.4},"doors":{"type":"integer","title":"Doors","description":"Number of doors","default":1},"windows_small":{"type":"integer","title":"Windows Small","description":"Small windows (~1.5 m²)","default":0},"windows_large":{"type":"integer","title":"Windows Large","description":"Large windows (~3 m²)","default":1},"previously_painted":{"type":"boolean","title":"Previously Painted","default":true},"new_plaster":{"type":"boolean","title":"New Plaster","description":"True triggers primer/mist-coat recommendations","default":false},"surface_texture":{"type":"string","title":"Surface Texture","description":"'smooth' or 'textured' — adjusts realistic coverage","default":"smooth"},"walls":{"anyOf":[{"$ref":"#/components/schemas/SurfaceColour"},{"type":"null"}],"description":"Wall colour"},"ceiling":{"anyOf":[{"$ref":"#/components/schemas/SurfaceColour"},{"type":"null"}],"description":"Ceiling colour"},"woodwork":{"anyOf":[{"$ref":"#/components/schemas/SurfaceColour"},{"type":"null"}],"description":"Skirting/architraves/window-surround colour"},"radiators":{"anyOf":[{"$ref":"#/components/schemas/SurfaceColour"},{"type":"null"}],"description":"Radiator colour"}},"type":"object","required":["name","length_m","width_m"],"title":"RoomSpec"},"SurfaceColour":{"properties":{"manufacturer":{"type":"string","title":"Manufacturer","description":"Brand name or slug, e.g. 'Farrow & Ball'"},"colour":{"type":"string","title":"Colour","description":"Colour name, slug, or number, e.g. 'Railings'"},"finish":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finish","description":"Optional finish name exactly as the brand sells it, e.g. 'Modern Emulsion'. Leave unset and the planner offers the available finishes."}},"type":"object","required":["manufacturer","colour"],"title":"SurfaceColour"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}