Trycolors API

The Trycolors API mixes paint colors, reverse-engineers a target color into a recipe from paints you name, and searches the Trycolors paint catalog.

1. Sign up for an account at trycolors.com/signin.
2. Generate your API key in your account settings.
3. Send the key in the X-API-KEY header on every request.

Base URL

https://api.trycolors.com/v1

Endpoints

Any other path under /v1/ is not part of the public API.

Example: mixing colors

const response = await fetch('https://api.trycolors.com/v1/mix-colors', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': process.env.TRYCOLORS_API_KEY
  },
  body: JSON.stringify({
    colors: [
      { hex: '#FFAA16', count: 1 },
      { hex: '#BA12FF', count: 1 }
    ],
    mixerMode: 'basic'
  })
});

const data = await response.json();
console.log(data.mixedColor); // "#DD5E8B"

Every request to the Trycolors API needs an API key.

Get an API key

1. Sign in to your Trycolors account at trycolors.com/signin.
2. Go to your account settings.
3. Find the API Keys card.
4. Click Generate API Key.
5. Copy your new key and store it somewhere safe.

Use your API key

Send the key in the X-API-KEY header of each request:

X-API-KEY: your_api_key_here

A request with no key returns 401 with the plain-text body Authentication required: X-API-KEY or X-Session-ID header. A request with a key we do not recognize returns 401 with Invalid API Key. Both bodies are plain text, not JSON, so do not parse them as JSON.

Keep your key safe

1. Never share your API key publicly or commit it to version control.
2. Store it in environment variables or a secret manager.
3. Rotate your API key from time to time.
4. If you think your key leaked, generate a new one and delete the old one in your settings. Deleting a key takes effect within two minutes, because key lookups are cached that long.

Every endpoint below is a POST to https://api.trycolors.com/v1/... with a JSON body and these headers:

Content-Type: application/json
X-API-KEY: your_api_key_here

All examples on this page were run against the live API. Responses are real, trimmed where marked.

Common behavior

• A missing key returns 401 with the plain-text body Authentication required: X-API-KEY or X-Session-ID header. An unknown key returns 401 with Invalid API Key. These two are plain text, not JSON.
• A path that is not listed on this page returns 404 with {"error":"Endpoint not found","docs":"https://api.trycolors.com/docs"}.
• Validation failures return 400 with {"error":"..."}.
• Over the rate limit returns 429. See Rate limits.
• Responses do not carry an engine version or a request id. If you store a recipe, store the engine, mixerMode and paint ids you sent with it.

Finds the mix of your paints that comes closest to a target color.

POST/v1/unmix-color

Request body

A colors entry is either a plain hex string:

["#00FFFF", "#FF00FF", "#FFFF00"]

or an object:

paint_id is what makes a recipe reproducible with real tubes. Without it the engine only knows the color you typed; with it the engine knows the pigment behind that color.

Modes and engines

Example request

{
  "colors": [
    { "hex": "#F7F5F1", "name": "Titanium White", "paint_id": 3554 },
    { "hex": "#19123F", "name": "Ultramarine Blue", "paint_id": 3656 },
    { "hex": "#FFC500", "name": "Cadmium Yellow Medium", "paint_id": 3573 },
    { "hex": "#673020", "name": "Burnt Sienna", "paint_id": 3610 },
    { "hex": "#5D162D", "name": "Quinacridone Magenta", "paint_id": 3650 }
  ],
  "targetHex": "#6E8B74",
  "maxColorsCount": 4,
  "maxDropsCount": 20,
  "mixerMode": "pro",
  "engine": "2025"
}

Those five paint ids are Golden Heavy Body tubes in the Trycolors catalog.

Example response

{
  "structure": [
    { "hex": "#F7F5F1", "name": "Titanium White", "count": 0.47368421052631576, "wholeParts": 9, "tintingStrength": 26, "paint_id": 3554 },
    { "hex": "#19123F", "name": "Ultramarine Blue", "count": 0.3157894736842105, "wholeParts": 6, "tintingStrength": 77, "paint_id": 3656 },
    { "hex": "#FFC500", "name": "Cadmium Yellow Medium", "count": 0.10526315789473684, "wholeParts": 2, "tintingStrength": 21, "paint_id": 3573 },
    { "hex": "#673020", "name": "Burnt Sienna", "count": 0.10526315789473684, "wholeParts": 2, "tintingStrength": 61, "paint_id": 3610 },
    { "hex": "#5D162D", "name": "Quinacridone Magenta", "count": 0, "wholeParts": 0, "tintingStrength": 67, "paint_id": 3650 }
  ],
  "mixedColor": "#718C76",
  "matchResult": 99.2,
  "ratioMixedColor": "#718C76",
  "ratioMatchResult": 99.2,
  "practicalSteps": [
    {
      "step": 1,
      "color": { "hex": "#FFC500", "name": "Cadmium Yellow Medium", "wholeParts": 2, "tintingStrength": 21 },
      "cumulative": { "#FFC500": 2 },
      "mixedColor": "#FFC500",
      "matchResult": 62.6
    },
    {
      "step": 2,
      "color": { "hex": "#F7F5F1", "name": "Titanium White", "wholeParts": 9, "tintingStrength": 26 },
      "cumulative": { "#FFC500": 2, "#F7F5F1": 9 },
      "mixedColor": "#FBEE76",
      "matchResult": 64.3
    },
    {
      "step": 3,
      "color": { "hex": "#673020", "name": "Burnt Sienna", "wholeParts": 2, "tintingStrength": 61 },
      "cumulative": { "#FFC500": 2, "#F7F5F1": 9, "#673020": 2 },
      "mixedColor": "#D7B06F",
      "matchResult": 71.8
    },
    {
      "step": 4,
      "color": { "hex": "#19123F", "name": "Ultramarine Blue", "wholeParts": 6, "tintingStrength": 77 },
      "cumulative": { "#FFC500": 2, "#F7F5F1": 9, "#673020": 2, "#19123F": 6 },
      "mixedColor": "#718C76",
      "matchResult": 99.2
    }
  ],
  "diagramSteps": [
    { "step": 1, "cumulative": { "#FFC500": 2 }, "mixedColor": "#FFC500" },
    { "step": 2, "cumulative": { "#FFC500": 2, "#F7F5F1": 1 }, "mixedColor": "#FFD800" },
    { "step": 18, "cumulative": { "#FFC500": 2, "#F7F5F1": 9, "#673020": 2, "#19123F": 6 }, "mixedColor": "#718C76" }
  ],
  "omittedColors": []
}

diagramSteps is trimmed above. The real call returned 18 steps, one per part added.

Response fields

Conditional fields

Three fields appear only in some responses. Treat all three as optional.

suggestedPigments and bestAchievableMatch appear when the match falls below 95. bestAchievableMatch is the match a full pigment set would reach, so you can tell "your palette cannot do this" from "this color is hard for anyone". suggestedPigments names up to a few paints that would close the gap.

{
  "matchResult": 90.9,
  "ratioMatchResult": 91,
  "bestAchievableMatch": 99.7,
  "suggestedPigments": [
    { "hex": "#002E2A", "name": "Phthalo Green (Yellow Shade)", "predictedMatch": 100, "gain": 9.01 },
    { "hex": "#00A1A4", "name": "Cobalt Teal", "predictedMatch": 99.8, "gain": 8.84 },
    { "hex": "#00656B", "name": "Cobalt Turquoise", "predictedMatch": 95.6, "gain": 4.59 }
  ]
}

That response came from the same five Golden tubes aimed at #00B894, a green they cannot reach.

dilution appears for trace recipes: pale targets that need a dose of strong pigment too small for any parts ratio, such as a cream that wants 0.3% cadmium red in white. When it is present the recipe splits in two. structure[].wholeParts becomes a small concentrate you mix first, structure[].count stays the final proportions, and mixedColor and matchResult describe the marked ladder stop, which is the color you end up with.

Errors

{ "error": "Invalid input colors. At least 2 valid colors are required." }
{ "error": "Invalid target hexadecimal color." }
{ "error": "maxColorsCount and maxDropsCount must be positive whole numbers." }
{ "error": "Invalid engine: 2024. Must be '2023' or '2025'." }

A 503 with {"error":"Unmixer service is temporarily unavailable..."} means the mixing service is down. Retry.

Mixes paints in the proportions you give and returns the result.

POST/v1/mix-colors

Request body

Example request

{
  "colors": [
    { "hex": "#F7F5F1", "count": 3, "paint_id": 3554 },
    { "hex": "#19123F", "count": 1, "paint_id": 3656 }
  ],
  "mixerMode": "pro",
  "engine": "2025"
}

Example response

{ "mixedColor": "#7FAEEB" }

The response is only the mixed color. Nothing else is returned.

Notes

• Paints with count: 0 are skipped by the 2025 path. If every count is 0, the response is {"mixedColor":"#000000"}.
• The 2025 path returns 400 when it cannot resolve mixing data for a color: {"error":"Could not get K/S data for color #XXXXXX: ..."}.
• Enamel paints only mix with enamels of the same brand. In a mixed request the enamel entries fall back to plain hex resolution, so the result is less accurate than a pure enamel mix.

Searches the Trycolors paint catalog by keyword, by color similarity, or by filters, with pagination.

POST/v1/paints/search

Request body

Every field is optional. A body with no search term and no filter returns the whole catalog sorted by name, page by page, so send at least one of q, color or a filter.

Example request

{
  "q": "quinacridone gold",
  "brand": ["daniel-smith"],
  "limit": 2
}

Example response

{
  "paints": [
    {
      "hex": "#BF7105",
      "paintName": "Quinacridone Gold",
      "sku": "",
      "brandName": "Daniel Smith",
      "brandId": 91,
      "lineName": "Original Oils",
      "mediumName": "Oil",
      "colorGroupName": "Black",
      "distance": null,
      "relevance": 205.76,
      "pigments": [
        { "id": 235, "code": "PO48", "name": "Quinacridone Burnt Orange", "colorIndex": null },
        { "id": 783, "code": "PY150", "name": "Nickel Azo Yellow", "colorIndex": null }
      ],
      "slug": "daniel-smith-original-oils-quinacridone-gold",
      "brandPath": "daniel-smith",
      "properties": {
        "transparency": "Transparent",
        "staining": "",
        "granulation": null,
        "lightfastness": "I – Excellent"
      }
    }
  ],
  "totalCount": 74
}

One of the two returned paints is shown.

Response fields

Finds catalog paints close to a hex code. This endpoint reads an older catalog snapshot than /paints/search, so it returns fewer fields, and its brandId and seriesIds belong to that snapshot. They are not the ids /paints/search returns: Daniel Smith is brand 173 here and brand 91 there.

POST/v1/similar-paints

Request body

Example request

{ "hex": "#FF0C13", "count": 3 }

Example response

{
  "paints": [
    { "hex": "#FF0C13", "paintName": "Red Orange", "sku": "203-F", "brandName": "1 Shot", "brandId": 1, "seriesName": "Fluorescent", "distance": 0 },
    { "hex": "#F70714", "paintName": "Cadmium Red Hue", "sku": "1420", "brandName": "Lukas", "brandId": 414, "seriesName": "Aquarell Studio", "distance": 1.8248703279757885 },
    { "hex": "#FF0015", "paintName": "Vermilion", "sku": "436", "brandName": "Marabu", "brandId": 424, "seriesName": "DecorGlass", "distance": 0.6234378309325322 }
  ]
}

Response fields

hex, paintName, sku, brandName, brandId, seriesName, distance. There is no lineName, no pigments, no slug and no paint id.

Other paths

A few other paths under /v1/ serve trycolors.com itself. They are not part of the public API, are not supported for third-party use, and can change without notice. Every path not listed on this page should be treated as unavailable, including any you may find by guessing.

Rate limits are per endpoint and per account, in two tiers. An API key you generate in your account settings gets the standard tier on a Hobby or Pro plan, and the Business tier on a Business plan.

Standard (Hobby and Pro individual plans)

Business plan

How the limits work

• The per-second counter resets one second after the first request in its window. The daily counter resets when the server's date rolls over.
• Limits are counted per endpoint, not shared across endpoints.
• Usage is counted per account, so several keys or servers on one account draw from the same allowance.

Handling 429

Over either limit the API returns 429 with a plain-text body: Rate limit exceeded: too many requests per second or Rate limit exceeded: daily limit reached. Back off and retry, with exponential backoff for the per-second case.

Good practice

1. Cache responses. Mixing the same paints at the same ratios always gives the same result.
2. Spread calls out rather than sending bursts.