Live production base URL
Use the current production host shown below. Every endpoint requires an active API key issued to an approved manual Beta account.
The commercial projection contains 161 cleared color records. The API does not provide an endpoint that lists or downloads color records.
The API is for server-to-server use. Browser CORS is intentionally unsupported.
https://api.chinesecoloratlas.com/v1Bearer API keys
Send the API key in the Authorization header. Store it on your server; never place it in browser JavaScript, a mobile application bundle, or a public repository.
POST /v1/match and GET /v1/search also require an Idempotency-Key containing 8–128 letters, numbers, periods, underscores, colons, or hyphens. Repeating the same key and request replays its result; using that key with different input is rejected. After a timeout, request_in_progress, 500, or 503, retry the exact same request with the same key. Honor Retry-After and use backoff for repeated server errors.
Authorization: Bearer $CATHYCOLOR_API_KEYPOST /v1/match
Submit 1–5 RGB colors per request. Each channel must be between 0 and 255. The optional top field accepts 1–3 and controls the number of matches returned for each input.
Each result includes the input, up to three matched records, reliability, deltaE, and similarity fields.
curl --request POST \
--url https://api.chinesecoloratlas.com/v1/match \
--header "Authorization: Bearer $CATHYCOLOR_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: match-2026-09-26-0001" \
--data '{"colors":[{"r":0,"g":52,"b":96}],"top":1}'GET /v1/search
Search Chinese names, English names, pinyin, stable slugs, or HEX values. Queries must contain 2–64 characters. The response is limited to at most 10 records.
curl --get \
--url https://api.chinesecoloratlas.com/v1/search \
--header "Authorization: Bearer $CATHYCOLOR_API_KEY" \
--header "Idempotency-Key: search-2026-09-26-0001" \
--data-urlencode "q=indigo" \
--data-urlencode "limit=5"| Parameter | Required | Meaning |
|---|---|---|
| q | Yes | Search text, 2–64 characters. |
| limit | No | Maximum results, from 1 to 10; defaults to 10. |
GET /v1/library
Returns dataset metadata for the authenticated account, including version and record count. It never returns a color-record array and cannot be used to paginate or export the library.
curl https://api.chinesecoloratlas.com/v1/library \
--header "Authorization: Bearer $CATHYCOLOR_API_KEY"GET /v1/usage
Returns committed, reserved, remaining, and limit values for both monthly usage meters. Match usage counts input colors; search usage counts searches.
Hard caps are 2,000 match input colors and 1,000 searches per UTC calendar month. The counters reset on the first day of the UTC month, independently of the paid period shown in your subscription schedule.
curl https://api.chinesecoloratlas.com/v1/usage \
--header "Authorization: Bearer $CATHYCOLOR_API_KEY"Errors and retry behavior
Responses include a request ID. Use it when asking support about a failed request, and do not include your API key in support messages.
| HTTP status | Meaning | What to do |
|---|---|---|
| 400 idempotency_key_required / body_required / invalid_json | The key or match request body is missing or invalid. | Correct the request before retrying. |
| 401 unauthorized | The API key is missing or invalid. | Check the server-side key configuration. |
| 403 account_unavailable | The account is unavailable. | Contact support with the request ID. |
| 409 idempotency_conflict | The key was already used with different input. | Keep the original request; use a new key only for a new request. |
| 409 request_in_progress | The request with this key is still running. | After Retry-After, retry the exact request with the same key. |
| 413 payload_too_large | The match body exceeds the server byte limit. | Reduce the body size. |
| 415 content_type_required | The request Content-Type is unsupported. | Send application/json for match requests. |
| 422 invalid_match_request / invalid_batch_size / invalid_rgb / invalid_top / invalid_query | A request field is invalid. | Correct the fields; do not retry unchanged. |
| 429 | Abuse rate limit or monthly quota reached. | Honor Retry-After and inspect the error code. |
| 500 internal_error | The server encountered an internal failure. | Retry the exact request with the same key and backoff. |
| 503 usage_commit_failed | The usage commit is temporarily unavailable. | Honor Retry-After; retry the exact request with the same key. |
Bounded queries, not a library download
The API returns only the bounded data needed for an authenticated match or search request. The library endpoint returns metadata only.
- Every endpoint requires an active API key.
- Match requests accept at most five input colors; search returns at most ten records.
- The CathyColor atlas remains publicly readable. Authorized API responses can also be copied; request and quota limits are not an anti-scraping guarantee.
- Browser CORS access to this API is unsupported; make requests from your server.