Free Paint Color Search API
Search 29,000+ real paint colors from all 21 major brands — with a plain sentence, a color name, a paint code, or a hex value. One GET request, JSON back, CORS open, no API key. Every result is a real, buyable paint with its SKU, hex, and LRV — never an invented color.
The Endpoint
GET https://compositepaint.com/api/colors/search?q={your query}q — what you're looking for. All of these work:
- A sentence: "calm warm sage, not too dark"
- A color name: "Agreeable Gray" — typos are fine
- A paint code: "SW 7029", "OC-65", "PPU3-7"
- A hex value: "#9CA88A" — returns the closest real paints by ΔE
limit — optional, 1–20 results (default 10).
A Real Example
GET https://compositepaint.com/api/colors/search?q=calm+warm+sage+for+a+north+bedroom&limit=3{
"query": "calm warm sage for a north bedroom",
"lane": "smart",
"understood": {
"hue": "green",
"lightness": "medium",
"temperature": "warm",
"vibrance": "muted",
"anchor": "#8A9A86"
},
"ignored": ["calm", "north", "bedroom"],
"results": [
{
"name": "Whispering Willow",
"brand": "Hirshfield's",
"sku": "H0082",
"hex": "#919C81",
"lrv": 31,
"deltaE": 3.2,
"url": "https://compositepaint.com/colors/hirshfields-whispering-willow/"
},
{
"name": "Suffield Green",
"brand": "Farrow & Ball",
"sku": "No. 77",
"hex": "#8A9D80",
"lrv": 31,
"deltaE": 3.3,
"url": "https://compositepaint.com/colors/farrow-ball-suffield-green/"
},
{
"name": "Leaflet",
"brand": "Sherwin-Williams",
"sku": "SW 9674",
"hex": "#8B987B",
"lrv": 30,
"deltaE": 3.4,
"url": "https://compositepaint.com/colors/sherwin-williams-leaflet/"
}
]
}The understood andignored fields keep it honest: you can always show your users exactly how the sentence was read, and which words weren't used.
Response Fields
| query | Your query, echoed back after normalization. |
| lane | "instant" (name / code / hex — answered by the deck engine directly) or "smart" (sentence read by AI). |
| understood | Smart lane only: exactly how the sentence was read — filter values plus an optional anchor hex. |
| ignored | Words the search could not use yet (room names, purposes). We show them so nothing is silently dropped. |
| note | Present only when AI parsing was briefly unavailable and keyword matching answered instead. |
| results[].deltaE | Perceptual distance (ΔE2000) from the anchor color, when the query pointed at one. Lower is closer; under ~2 reads as the same color. |
| results[].lrv | Light Reflectance Value (0–100) — how much light the color bounces back. |
| results[].url | The color’s page on CompositePaint, with swatches, similar colors, and room previews. |
MCP Server for AI Agents
The same search is available as a remote MCP server, so agents (Claude, and any MCP-capable client) can plug it in directly as a tool:
https://compositepaint.com/api/mcpOne tool: search_colors(arguments: query, optional limit). Same query, same colors — the website search box, the REST endpoint, and the MCP tool share one engine.
How to Connect
Claude (web or desktop): Settings → Connectors → Add custom connector → paste the URL above. No login, no key — it connects instantly.
Claude Code:
claude mcp add --transport http compositepaint https://compositepaint.com/api/mcpOther MCP clients (Cursor, ChatGPT connectors, and any app that speaks Streamable HTTP): add it as a remote MCP server with the same URL. No authentication is required.
Then just ask your assistant something like "find me a calm warm sage for a north-facing bedroom" — it will search our real color database and answer with actual paints, SKUs, and links.
Fair-Use Limits
The API is free and needs no key. Name, code, and hex queries are answered directly from our color database and are effectively unlimited. Sentence queries use AI to read the sentence, so they share a sitewide daily budget plus per-minute caps; popular sentences are cached and don't count against it.
If the budget is briefly exhausted, sentence queries still work — they fall back to keyword matching and the response carries anote field saying so. Your integration never has to handle a dead search.
If you're building something that needs more headroom, emaildavid@compositepaint.com— we're happy to work something out. We only ask that you keep theurl links back to our color pages when you show results to users.