Catalogue API
Every vehicle make, model and year, and every colour that fits them, over plain REST with JSON answers. This page lists each endpoint, its parameters and the fields you get back.
On this page
Start here
| Item | Value |
|---|---|
| Base URL | https://api.mycarcolor.com |
| Format | JSON over HTTPS. Send Accept-Encoding: gzip to get compressed answers (curl: --compressed). |
| Method | Every endpoint here is a GET. |
| Ids | make, model and colour ids are stable. Look them up once and store them. |
| Endpoint | What it does |
|---|---|
/motomix/makes | Every vehicle make. |
/motomix/makes/{brand_id}/models | The models of one make. |
/motomix/makes/{brand_id}/models/{model_id}/years | The years of one model. |
/search/v3/ | Colours, by text, by vehicle, or both. |
/colors/ | The whole colour list in pages, or only what changed since a date. |
Want to try it first? Get a free test key. The vehicle picker and search are covered by it.
Authentication
Send your API key and secret, joined by a colon, in the Authorization header of every request.
Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET
Create and rotate keys in the client portal. The secret is shown once, so store it when you create the key. Keep keys on your server, never in browser or app code that others can read. If a key leaks, revoke it and make a new one.
A free test key is one form away at /developers#key. Test keys have lower limits; see Test key limits.
curl --compressed \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \ "https://api.mycarcolor.com/motomix/makes"
List the makes
GET /motomix/makes
Returns every make. No parameters. Use a make’s brand_id in the next calls and in colour search.
curl --compressed \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \ "https://api.mycarcolor.com/motomix/makes"
{
"count": 2,
"makes": [
{ "brand_id": "bada04e2ca39adbbed49a99b45015f1c", "brand_name": "Volkswagen", "logo_url": "https://…/volkswagen.svg" },
{ "brand_id": "…", "brand_name": "Tesla", "logo_url": "https://…/tesla.svg" }
]
}| Field | Meaning |
|---|---|
count | How many makes are in the list. |
makes[].brand_id | The make’s id. |
makes[].brand_name | The make’s name. |
makes[].logo_url | Where its logo is kept. Not every make has one, so be ready to show the name alone. |
List the models
GET /motomix/makes/{brand_id}/models
| Parameter | Meaning |
|---|---|
brand_id | A make’s id from the makes list. |
curl --compressed \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \ "https://api.mycarcolor.com/motomix/makes/bada04e2ca39adbbed49a99b45015f1c/models"
{
"brand_id": "bada04e2ca39adbbed49a99b45015f1c",
"brand_name": "Volkswagen",
"count": 2,
"models": [
{ "model_id": "c6929a3c2e61efa286a7abf87aed1b58", "brand_id": "bada04e2ca39adbbed49a99b45015f1c", "model_name": "Golf" },
{ "model_id": "…", "brand_id": "bada04e2ca39adbbed49a99b45015f1c", "model_name": "Passat" }
]
}| Field | Meaning |
|---|---|
brand_id, brand_name | The make you asked for. |
count | How many models are in the list. |
models[].model_id | The model’s id. |
models[].model_name | The model’s name. |
An unknown make gives a 404.
List the years
GET /motomix/makes/{brand_id}/models/{model_id}/years
| Parameter | Meaning |
|---|---|
brand_id | A make’s id. |
model_id | A model’s id from the models list. |
curl --compressed \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \ "https://api.mycarcolor.com/motomix/makes/bada04e2ca39adbbed49a99b45015f1c/models/c6929a3c2e61efa286a7abf87aed1b58/years"
{
"brand_id": "bada04e2ca39adbbed49a99b45015f1c",
"model_id": "c6929a3c2e61efa286a7abf87aed1b58",
"model_name": "Golf",
"years": [1974, 1975, 1976, "…", 2025, 2026]
}The years list holds whole years. An unknown make or model gives a 404.
Search colours
GET /search/v3/
Search every colour by code, name or make, or list the colours that fit a vehicle. The search forgives typos and puts the best matches first. Combine q with the vehicle parameters to search inside one vehicle.
| Parameter | What it does |
|---|---|
q | Text to search for: a code, a name or a make. Up to 100 characters. |
id | Look up one colour by its color_id. q is then ignored. |
brand_id | Only colours for this make. Take it from the makes list. |
model_id | Only colours for this model. Needs brand_id. |
year | Only colours that fit this year. Take it from the years list. A whole number. |
fitment | On a vehicle search (make, model and year): strict returns the factory colours, or the confirmed ones if there is no factory list. all returns every colour that fits. Any other value is a 422. |
page | Page number, from 1. The default is 1. |
page_size | Results a page, 1 to 50. The default is 20. Above 50 is a 422. |
group | The default true shows one card per paint, even if the paint has several codes. Use group=false to list every code and shade variant. |
fields | Optional. A comma-separated list of the fields you want per colour, for example brand_name,color_code,color_name. |
A vehicle is always named by ids from the three lists above, never by its name. A year on its own is accepted but works best with a make.
Search by text
curl --compressed \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \ "https://api.mycarcolor.com/search/v3/?q=cosmic+silver&page_size=20"
Search by vehicle
curl --compressed \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \ "https://api.mycarcolor.com/search/v3/?brand_id=bada04e2ca39adbbed49a99b45015f1c&model_id=c6929a3c2e61efa286a7abf87aed1b58&year=2016"
The year knows model generations, so a 2016 Golf returns the colours of its own generation and not of earlier Golfs.
Response
{
"hits": [
{
"color_id": "3f2a9c41d07e85b6a1c4e9027fd35b8c61a0e7d2",
"brand_name": "TESL",
"color_code": "2DB",
"color_name": "COSMIC SILVER M.",
"year": "2021/",
"rgb_hex": "#a7aaae",
"color_family": "Silver",
"image_url": "https://…/2db.jpg",
"region": "EU",
"is_metallic": true,
"is_pearl": false,
"is_xirallic": false,
"is_candi": false,
"is_special_effect": false,
"is_variant": false,
"brands": [{ "brand_id": "…", "brand_name": "TESL" }],
"enrichment": { "is_tricoat": false }
}
],
"total_hits": 1,
"page": 1,
"page_size": 20,
"total_pages": 1,
"processing_time_ms": 4
}Every answer also carries the paging fields total_hits, page, page_size, total_pages and processing_time_ms. To read every page, raise page until it reaches total_pages.
/colors/search/ is an older route that takes the same text and vehicle parameters and gives the same colour fields. New work should use /search/v3/.
Colour fields
Each colour in hits (and in colors on the colour list) has these fields. They are the same in a text search and a vehicle search.
| Field | Meaning |
|---|---|
color_id | The colour’s permanent id. Store it and use it with the id parameter to fetch the colour again. |
brand_name | The paint brand’s short code, for example VW or TESL. |
color_code, color_name | The manufacturer’s code and name, for example 2DB and COSMIC SILVER M. |
year | First and last year of use, such as 2012/2019. An open end (2021/) means still in use. |
rgb_hex, rgb | An approximate on-screen colour, as #rrggbb and as red, green and blue. |
color_family | A plain family such as Silver, Blue or Black, for filters. |
image_url | A photo of the paint chip. Not every colour has one, so fall back to rgb_hex. |
region | The market the colour belongs to. |
is_metallic, is_pearl, is_xirallic, is_candi, is_special_effect | The finish, as true or false. |
is_variant | True for a shade variant of another colour. |
brands[] | The brands that carry the colour: brand_id and brand_name. |
enrichment.is_tricoat | True for a three-stage (tri-coat) paint. |
Your key may include extra fields, such as the vehicles a colour fits, other names and codes, and the factory finish. They are set for each key and are not listed here.
The colour list
GET /colors/
Pages through every colour your key can see, in the same shape as a search hit. It is for keys with the list switched on. Without it, the call gives a 403. Use updated_since to fetch only what changed since your last run.
| Parameter | What it does |
|---|---|
offset | How many colours to skip. Starts at 0. |
limit | Colours in a page, 1 to 1000. The default is 1000. |
updated_since | An ISO 8601 time, for example 2026-10-01T00:00:00Z. A date alone is midnight UTC, and a time with no offset is read as UTC. Write a + offset as %2B. Only colours changed at or after it come back. |
fields | Optional. A comma-separated list of the fields you want per colour. |
curl --compressed \ -H "Authorization: Bearer YOUR_API_KEY:YOUR_API_SECRET" \ "https://api.mycarcolor.com/colors/?offset=0&limit=1000&updated_since=2026-10-01T00:00:00Z"
{
"colors": [
{
"color_id": "8e61b0d4a29c7f35e1d08a46b93c5f20d7e14a68",
"brand_name": "VW",
"color_code": "L352",
"color_name": "Mauritius Blue",
"year": "2012/2019",
"rgb_hex": "#3b5f8a",
"is_metallic": true,
"is_pearl": false,
"…": "…"
}
],
"pagination": {
"offset": 0,
"limit": 1000,
"total": 1,
"has_next": false,
"has_previous": false,
"current_page": 1,
"total_pages": 1
}
}This list pages with offset and limit, not page and page_size. Step offset up by limit until has_next is false. With updated_since, pagination.total counts only the changed colours.
A colour counts as changed when its data changes: its name, code, colour value, vehicles, image or other names. A colour being removed does not show up, so pull the whole list now and then, for example weekly. Store the time you started a run and use it as the next updated_since, so nothing slips between two runs.
A time that cannot be read, or that is in the future, is a 400 with a plain message, such as updated_since must be an ISO-8601 timestamp, e.g. 2026-10-01T00:00:00Z.
Errors
Errors use the HTTP status and a JSON body. The body has a detail or an error and message that say what went wrong.
| Status | What it means and what to do |
|---|---|
400 | A bad updated_since on the colour list. On a test key, a page beyond the ones it may read. |
401 | The key or secret is missing or wrong, or the key is revoked or expired. Check the header, then the portal. |
403 | Your key does not include this endpoint, or the key is paused. |
404 | A make or model id does not exist. Take ids from the lists, not from memory. |
422 | A parameter is invalid, such as page_size over 50, or fitment other than strict or all. |
429 | Too many requests. Wait for the Retry-After header, in seconds, then try again. |
500 to 599 | A fault on our side. Wait a moment and retry. If it keeps happening, tell your MyCarColor contact. |
HTTP/1.1 401 Unauthorized
{ "detail": "Invalid API key or secret, or client is inactive" }HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 10 per 1 second
{
"error": "Rate limit exceeded",
"message": "Rate limit exceeded: 10 per 1 second",
"limit": "10 per 1 second",
"retry_after": 1
}HTTP/1.1 500
{
"error": "search_failed",
"message": "The search could not be completed. Please try again."
}Rate limits
| Endpoints | Limit |
|---|---|
| Makes, models, years and /search/v3/ | Requests a second for each key. The default is 10, and your agreement can set another figure. |
/colors/ | 6 requests a minute for each key, and one request at a time. Pages are large, so fetch a page, then the next. |
The limit belongs to each key, however many machines call with it. One key’s calls never use up another key’s allowance. Past a limit you get a 429 with a Retry-After header and an X-RateLimit-Limit header, as shown under Errors. A second /colors/ call while one is running gets the same shape with limit set to 1 in flight.
Fair use: read what you need, cache what you can, and space requests out. Show the data in your product and keep it for your own customers. Redistribution and bulk copying are not allowed.
Test key limits
A free test key is for trying the API. Keys from the portal that start with portal_ are test keys, and they have extra limits that a live account does not.
| Limit | Value |
|---|---|
| Endpoints | Makes, models, years and /search/v3/ only. Other endpoints, including /colors/, are refused. |
| Results a page | Up to 20. Ask for page_size 20 or less. |
| Pages | The first 5 pages of a search, and the first 2 pages of a broad listing: by make only, by year only, or with no query. Narrow the search to reach other colours. |
| Calls a day | 2,000 for your company, all test keys together. The count resets at 00:00 UTC. |
| Bursts | Limited per minute (30 by default) as well as per second. Space requests out. |
On a test key, total_hits and total_pages count only what the key can reach. Past a limit you get a 400 (a page it may not read) or a 429 (today’s limit or a burst: wait, then retry). A key that copies the data wholesale with automated calls is paused with a 403. Contact MyCarColor to resume.