DevelopersCatalogue API reference

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

The basics
ItemValue
Base URLhttps://api.mycarcolor.com
FormatJSON over HTTPS. Send Accept-Encoding: gzip to get compressed answers (curl: --compressed).
MethodEvery endpoint here is a GET.
Idsmake, model and colour ids are stable. Look them up once and store them.
Endpoints
EndpointWhat it does
/motomix/makesEvery vehicle make.
/motomix/makes/{brand_id}/modelsThe models of one make.
/motomix/makes/{brand_id}/models/{model_id}/yearsThe 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" }
  ]
}
Make fields
FieldMeaning
countHow many makes are in the list.
makes[].brand_idThe make’s id.
makes[].brand_nameThe make’s name.
makes[].logo_urlWhere 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

Path parameters
ParameterMeaning
brand_idA 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" }
  ]
}
Model fields
FieldMeaning
brand_id, brand_nameThe make you asked for.
countHow many models are in the list.
models[].model_idThe model’s id.
models[].model_nameThe model’s name.

An unknown make gives a 404.

List the years

GET /motomix/makes/{brand_id}/models/{model_id}/years

Path parameters
ParameterMeaning
brand_idA make’s id.
model_idA 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.

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.

Colour fields
FieldMeaning
color_idThe colour’s permanent id. Store it and use it with the id parameter to fetch the colour again.
brand_nameThe paint brand’s short code, for example VW or TESL.
color_code, color_nameThe manufacturer’s code and name, for example 2DB and COSMIC SILVER M.
yearFirst and last year of use, such as 2012/2019. An open end (2021/) means still in use.
rgb_hex, rgbAn approximate on-screen colour, as #rrggbb and as red, green and blue.
color_familyA plain family such as Silver, Blue or Black, for filters.
image_urlA photo of the paint chip. Not every colour has one, so fall back to rgb_hex.
regionThe market the colour belongs to.
is_metallic, is_pearl, is_xirallic, is_candi, is_special_effectThe finish, as true or false.
is_variantTrue for a shade variant of another colour.
brands[]The brands that carry the colour: brand_id and brand_name.
enrichment.is_tricoatTrue 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.

Colour list parameters
ParameterWhat it does
offsetHow many colours to skip. Starts at 0.
limitColours in a page, 1 to 1000. The default is 1000.
updated_sinceAn 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.
fieldsOptional. 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 codes
StatusWhat it means and what to do
400A bad updated_since on the colour list. On a test key, a page beyond the ones it may read.
401The key or secret is missing or wrong, or the key is revoked or expired. Check the header, then the portal.
403Your key does not include this endpoint, or the key is paused.
404A make or model id does not exist. Take ids from the lists, not from memory.
422A parameter is invalid, such as page_size over 50, or fitment other than strict or all.
429Too many requests. Wait for the Retry-After header, in seconds, then try again.
500 to 599A 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

Rate limits
EndpointsLimit
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.

Test key limits
LimitValue
EndpointsMakes, models, years and /search/v3/ only. Other endpoints, including /colors/, are refused.
Results a pageUp to 20. Ask for page_size 20 or less.
PagesThe 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 day2,000 for your company, all test keys together. The count resets at 00:00 UTC.
BurstsLimited 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.

Ready for more? See plans or get a key.