API Documentation — Colour Memory

Overview

Two ways to use Colour Memory: via the MCP server (recommended for AI agents and Claude) or the REST API (for direct integration). Both use the same archive and return the same structured data.

Every response includes a primary source citation, a confidence score (0.0–1.0), a claim strength grade (A–E), epistemic guardrails (do_not_say), and cultural risk flags. No generated data. No guesses.

Using Claude, Cursor, or any MCP client? Add the MCP server at https://colour-memory-api-production.up.railway.app/mcp — all all tools register automatically. See MCP Server.

Free colour APIs tell you what a colour is called. Colour Memory tells you what it means, where it came from, and whether it will get you in trouble.

Get an API key

Two free tiers. No credit card required to start.

Free Explorer

Free

No email required

25 archive calls · 3 Intelligence credits · IP limited · No export

Developer

Free

Email required

500 archive calls · 10 Intelligence credits · API key · Usage dashboard

For paid plans (Studio £12, Pro £39, Founder Enterprise £299) see Pricing. Keys are issued at colourmemory.com/start.

Quickstart

Match a hex colour to the archive in one call:

cURL

curl https://colour-memory-api-production.up.railway.app/query/hex \
  -H "X-Api-Key: your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"hex": "#D4A829"}'
        

Response

{
  "name":            "Song Gold Sycee",
  "hex":             "#D4A829",
  "archive":         "China",
  "primary_source":  "Song dynasty imperial gold currency ingots",
  "confidence":      0.97,
  "claim_strength":  "A",
  "cultural_risk":   "low",
  "do_not_say":      []
}
        

Authentication

Pass your API key in the X-Api-Key request header on all authenticated requests.

Header

X-Api-Key: cm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requests without a key are rate limited by IP and return a 401 after the free preview limit is exhausted.

Intelligence credits

Colour Memory has two types of call:

Archive calls

Search, match, retrieve, forensics, accessibility, palette tools. Fast, cheap, generous limits. Does not consume Intelligence credits.

Intelligence credits

AI analysis — session briefs, brand reports, ecommerce copy, palette verdicts, name generation. Standard tools cost 1 credit. Heavy tools (forensic brief, brand report) cost 3 credits.

Every response from an Intelligence endpoint includes _intelligence_credits_remaining so you always know your balance. When credits reach zero, archive tools keep working. Top up at colourmemory.com/pricing.

If a Claude API call fails (timeout, error) after credit deduction, credits are automatically refunded. You never pay for a failed call.

MCP Server

Colour Memory ships as a full MCP server. Connect once and all all tools are available to your AI agent without any additional code.

https://colour-memory-api-production.up.railway.app/mcp

Setup — Claude Desktop

Open Claude Desktop settings and add to your MCP config:

claude_desktop_config.json

{
  "mcpServers": {
    "colour-memory": {
      "url": "https://colour-memory-api-production.up.railway.app/mcp",
      "headers": {
        "X-Api-Key": "your_key_here"
      }
    }
  }
}
        

Also available on Smithery and Glama for one-click connection.

Setup — ChatGPT

In ChatGPT, go to Settings → Connectors → Add connector. Enter the MCP URL above and your API key. All tools register automatically.

All all tools

Tools are grouped by function. Archive tools use archive calls. Intelligence tools use credits.

Archive & retrieval

archive_search

Full-text search by name, material, period, or culture across the full archive.

query_hex

Match any hex to nearest archive colour using CIEDE2000 perceptual distance.

query_conceptual

Semantic search by mood, concept, or cultural theme. "Ottoman luxury," "Victorian grief."

colour_card

Full provenance record by colour name or slug.

archive_status

Archive health, colour count, and embedding model status.

archive_audit

Data quality audit for any named archive.

Colour intelligence 1 credit

colour_dna

Compact semantic fingerprint: depth, temperature, chroma, material register, emotional register.

colour_strategy

Commercial signal, market reading, usage rules, palette roles.

colour_verdict

Use with confidence / use with caution / avoid. Strengths, risks, better alternatives.

colour_forensics

Substrate safety, three-illuminant light behaviour, material risks.

colour_namer

Archive-verified product colour names. Geographical, poetic, literary, material styles.

colour_hooks

Memory hooks — the single most surprising fact from each archive entry.

archive_cliche

Cliche contradiction — subvert the expected colour for any concept.

colour_story

Cultural narrative for any colour. What it meant, where it came from.

Brand & commercial 1 credit 3 credits (report)

brand_collision

Can this brand own this colour in this market? Competitor distance, ownership risk.

brand_audit

Palette roles, WCAG matrix, cultural risk per colour, design tokens. No LLM cost.

brand_report 3

Full brand colour strategy: editorial argument, market readings, copy package, image prompt.

ecommerce_copy

Product title, description, SEO meta, alt text, Instagram caption — archive-grounded.

ecommerce_namer

Archive-verified colour names for up to 40 product SKUs in one call.

cultural_risk

Cultural sensitivity score across global markets. Warnings, positives, context flags.

Session & forensic briefs 3 credits

session_brief

One call: colour cards, editorial argument, act structure, pull quote, image prompt.

archive_report_brief

Forensic research brief from an archive query. Evidence, gaps, anachronisms.

archive_evidence_gap

Anti-hallucination: is this claim supported by the archive?

archive_coverage_gap

Which themes in a brief are under-evidenced?

cultural_anachronism

Period mismatch detection. Flags anachronistic colours in historical briefs.

index_resonance

Material-consequence alignment score with sub-scores across archive categories.

Palette tools

palette_generate

Fill palette gaps from the archive. Lock some slots, fill the rest.

palette_verdict 1

Score 0–100. Weakest colour. Concrete suggestion for what to add.

palette_iterate 1

Refine with natural language. "More melancholic." "Less corporate."

palette_compare 1

Deep comparison: timelessness, commercial strength, cultural depth, winner verdict.

palette_export

CSS variables, Figma tokens, Tailwind config, JSON. Archive names in comments.

palette_audit

Accessibility, cultural risk, tonal balance, naming strength. Full quality score.

palette_light_dark

Light and dark mode role maps. Missing neutrals, contrast safety, surface assignments.

palette_concept 1

Generate a palette from a historical or cultural concept.

Accessibility & design systems

accessibility_check

WCAG 2.1 AA/AAA contrast ratios for any colour pair.

accessibility_matrix

Full WCAG matrix in one call. Every foreground/background pair with grades.

accessibility_rules

Safe pairs, large-text-only pairs, component usage rules from your palette.

accessibility_font

Font colour ranked by contrast ratio with WCAG grades for any background.

colour_slugs

CSS variable, Tailwind class, TypeScript const, kebab, camelCase — one call.

accessibility_simulate

CVD simulation: protanopia, deuteranopia, tritanopia. Brettel-Vienot-Mollon model.

Image & AI agent tools 1 credit

agent_brief

Archive palette → Midjourney/DALL-E/Flux prompt with archive colour names and hex tokens.

agent_verify

Did your AI image generator use the specified colours? fidelity score, dE2000 per colour.

image_palette

Extract dominant colours from an image and map to archive entries.

image_personal

Personal colour analysis from a portrait. 12-season system. Best and avoid colours.

Core endpoints

query_hex — Match by hex

Field	Type	Description
hexrequired	string	Hex value e.g. `#D4A829`
n_resultsoptional	integer	Number of matches. Default 1, max 10.
archiveoptional	string	Restrict to a named archive.

query_conceptual — Semantic search

Uses sentence-transformer embeddings. Abstract queries like "grief," "Ottoman luxury," or "toxic chemistry" return real archive results.

Field	Type	Description
queryrequired	string	Natural language query
n_resultsoptional	integer	Default 5, max 20.
archiveoptional	string	Restrict to a named archive.

archive_search — Keyword search

Field	Type	Description
qrequired	string	Search term — name, material, pigment, period
archiveoptional	string	Restrict to a named archive.
limitoptional	integer	Default 10, max 50.

session_brief — Forensic brief 3 credits

One call returns colour cards, editorial argument, act structure, pull quote, closing line, and Midjourney/Flux image prompt. Uses Opus model — costs 3 Intelligence credits.

brand_collision — Colour ownership

Checks competitor distance, cultural context, and ownership risk. Returns verdict with reasoning.

ecommerce_copy — Product copy 1 credit

Returns product title, short description, long description, SEO title, meta description, alt text, and Instagram caption — all grounded in archive provenance.

accessibility_matrix — Full WCAG matrix

Field	Type	Description
paletterequired	array	Array of hex values e.g. `["#D4A829", "#0A0A0B"]`

Response schema

Every colour result includes these fields:

name

string

Archive colour name

hex

string

Hex value e.g. #D4A829

Claim strength grades

A

Highest

Direct institutional record — museum catalogue, primary manuscript, royal decree

B

Strong

Contemporary written account from a named observer

C

Moderate

Secondary historical source or established scholarly consensus

D

Weak

Inferred from material or cultural context

E

Poetic

Interpretive — literary or artistic inference only

Error codes

401

Unauthorized

Missing or invalid API key

402

Payment Required

Insufficient Intelligence credits. Top up at colourmemory.com/pricing

404

Not Found

Colour or archive not found

429

Rate Limited

Too many requests. Slow down or upgrade tier.

502

Service Error

Claude API error. Credits automatically refunded.

Health endpoint

cURL

curl https://colour-memory-api-production.up.railway.app/health

Returns API version, archive list, colour count, search method, and embedding model. No key required.