API integration guide

What the API can do

Your server can match RGB values, search color names, and read library and usage metadata for 161 colors. The API does not provide a full-catalog download, and browsers cannot call it directly because CORS is not supported.

1. Download and extract the tools

You need Node.js 20 or later. These examples use a POSIX-compatible shell, such as Terminal on macOS or Linux. Native Windows commands have not been verified. The ZIP contains the customer-side helper scripts; it does not contain color data or an API key. No npm install is needed.

API setup tools (ZIP)

Save the ZIP in Downloads, extract it to a private working folder, then run the commands from that folder:

mkdir -p ~/cathycolor-api
unzip ~/Downloads/key-delivery-tools.zip -d ~/cathycolor-api
cd ~/cathycolor-api
node --version

The extracted folder contains tools/api-key-delivery/. Keep your working files outside your website's public directory and source control.

2. Generate your public and private key files

For an existing customer key change supported by API support, the public JWK file lets CathyColor encrypt an API key so only the matching private key can unlock it. Share a public file only when support requests it; keep the private file on a device you control. JWK is a JSON format for key files.

Run this from the extracted folder:

umask 077
node tools/api-key-delivery/generate-keypair.mjs \
  --public-out ./customer.public.jwk \
  --private-out ./customer.private.jwk

The tool creates a 3072-bit RSA key pair for RSA-OAEP with SHA-256, writes both files with mode 0600, and refuses to overwrite existing files.

Confirm both files were created:

ls -l ./customer.public.jwk ./customer.private.jwk

3. Existing-customer account and key support

New API sales and new customer provisioning are paused. Existing customers can continue using the API with active keys; renewals and support continue. Email support from your account email for existing-account help. support@chinesecoloratlas.com

Include your account email and relevant X-Request-Id. Share a public JWK only if support requests it for an existing-account key change.

Account email: the existing account email
To: support@chinesecoloratlas.com
Subject: CathyColor API support
Optional attachment: customer.public.jwk only if support requests it for an existing-account key change

Never attach customer.private.jwk, an API key, a full Authorization header, or payment-card details. Do not paste either key into a public issue or chat.

4. Read an encrypted key receipt

If support provides an encrypted key receipt for an existing-account key change, save it as provisioning-receipt.json in your private working folder. It contains the API key as encrypted data, not as readable text. Keep the file unchanged and private.

Run the decryptor with your private JWK:

umask 077
node tools/api-key-delivery/decrypt-envelope.mjs \
  --envelope ./provisioning-receipt.json \
  --private-key ./customer.private.jwk \
  --key-out ./cathycolor.api-key \
  --purpose cathycolor_api_key_provisioning

The tool validates the receipt and writes the API key to cathycolor.api-key with mode 0600. It does not print the key and will not overwrite an existing output file. Store the key in your secret manager; never send it to support.

5. Verify the key once

Use the active key issued to your account. The check calls /v1/library (no quota charge) and makes one /v1/search request (one search unit). Each additional run uses another search unit.

This example searches for red:

node tools/api-key-delivery/verify-key.mjs \
  --key-file ./cathycolor.api-key \
  --base-url https://api.chinesecoloratlas.com \
  --query red

Success reports HTTP 200 for both library.status and search.status. The tool discards response bodies and prints status plus non-sensitive usage metadata. If either status differs, keep the request details and contact support without sending the key.

6. API reference

Send requests from your backend to the production host. Keep the API key in a secret store, turn off shell tracing while it is loaded, and do not export it.

Read library and usage metadata

• GET /v1/library — Release metadata only; no quota charge.
• GET /v1/usage — Current UTC-month usage for both meters; no quota charge.
• POST /v1/match — Each RGB color in a match request uses one match input. colors accepts 1–5 RGB values; optional top is 1–3.
• GET /v1/search — Each search uses one search unit. q must contain 2–64 characters after trimming; limit is at most 10.

/v1/library returns release metadata, not color records. Match and search return bounded results from the 161-color set; there is no endpoint for the full catalog.

Match and search

set +x
API_BASE_URL="https://api.chinesecoloratlas.com"
API_KEY_FILE="./cathycolor.api-key"
API_KEY="$(tr -d '\n' < "$API_KEY_FILE")"

curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  "$API_BASE_URL/v1/library"

curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  "$API_BASE_URL/v1/usage"

MATCH_IDEMPOTENCY_KEY="match-$(node -e 'process.stdout.write(require("node:crypto").randomUUID())')"
curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $MATCH_IDEMPOTENCY_KEY" \
  --data '{"colors":[{"r":12,"g":34,"b":56}],"top":2}' \
  "$API_BASE_URL/v1/match"

SEARCH_IDEMPOTENCY_KEY="search-$(node -e 'process.stdout.write(require("node:crypto").randomUUID())')"
curl --silent --show-error --include \
  --header "Authorization: Bearer $API_KEY" \
  --header "Idempotency-Key: $SEARCH_IDEMPOTENCY_KEY" \
  "$API_BASE_URL/v1/search?q=black&limit=3"

unset API_KEY

Each RGB color in a match request uses one match input. colors accepts 1–5 RGB values; optional top is 1–3. Each search uses one search unit. q must contain 2–64 characters after trimming; limit is at most 10.

Retry metered requests safely

POST /v1/match and GET /v1/search require an Idempotency-Key (8–128 ASCII letters, digits, ., _, :, or -). Generate one key for each new logical request. After a timeout, 5xx, or request_in_progress, retry the exact same request with the same key. A replay does not charge again. Reusing a key with different request data returns 409 idempotency_conflict; use a new key only for a genuinely new request.

Common errors

• 401 — The API key is missing, invalid, revoked, or expired. Check the secret file and Authorization header; never include the key in a support message.
• 403 `account_unavailable` — Stop retrying and contact support with the request ID and error details.
• 409 — Resolve the idempotency conflict or retry an in-progress request with the same key and exact request.
• 422 — Correct invalid input, such as an RGB value outside 0–255 or a search query outside the allowed length.
• 429 `rate_limited` is an abuse-protection limit; honor `Retry-After` (normally 60 seconds). `quota_exceeded` means the monthly hard limit is used; honor its retry hint (normally 86,400 seconds), but that hint does not mean the monthly quota resets then. Only quota errors include usage headers. Do not retry in parallel to bypass either limit.
• 500 or 503 — If a metered request has an uncertain result, retry the same request with the same idempotency key and back off between attempts.

Need help?

Email support with the subscription email, endpoint path, UTC time, HTTP status, error code, and X-Request-Id. Do not include request bodies, RGB values, search terms, private keys, API keys, or Authorization headers. support@chinesecoloratlas.com

Reference downloads

The steps above are complete online. For offline use, choose the guide in the same language as this page. The other files serve specific developer tasks: