API Documentation

Overview

Pass a hex value, a colour name, or a natural language query. Get back a structured response covering eight dimensions of colour intelligence: name, archive, provenance, material integrity, CIE Lab, LRV, gamut warnings, WCAG accessibility, colour blindness simulation, and any cultural or regulatory advisory flags.

The archive spans RAL Classic, BS 4800, Munsell, AS 2700, ISCC-NBS, Shakespeare, Keats, Japan, Netherlands (Dutch Golden Age), Islamic geometric and manuscript tradition, PigmentHistorical (Cennini 1390 through Church 1890), Dark History, Brazil, American Archive, and the Digby Heritage collection. The Resonance Index maps Cross-archive resonance indexed by perceptual distance.

Get an API key

The first 100 calls require no authentication. For production use, request a key below and include it as an X-API-Key header on every request.

Quickstart

Match a hex colour to the archive in one call:

curl "https://colour-memory-api-production.up.railway.app/match?hex=%23D4820A"

{
  "name":         "Mango Cow",
  "hex":          "#D4820A",
  "archive":     "Material Culture",
  "integrity":   "Pigment",
  "lab":         [55.2, 22.8, 54.1],
  "lrv":         18.4,
  "confidence":  0.984,
  "gamut": { "srgb_risk": true, "p3_safe": true, "cmyk_risk": false },
  "wcag": { "on_white": "AA large", "on_black": "AAA" },
  "warning":     "Halal-disqualified. Indian Govt report 1908."
}

Authentication

Pass your API key in the X-API-Key request header. Unauthenticated requests are accepted up to a limit of 100 lifetime calls per IP address.

X-API-Key: cm_live_xxxxxxxxxxxxxxxxxxxx

Endpoints

/match — Colour matching

/colour/{name} — Direct lookup

GET /colour/Godstow%20Ultramarine
GET /colour/mango-cow

/mix — Pigment compatibility

POST /mix
{
  "pigments": ["Verdigris", "White Lead"],
  "medium": "oil"
}

// Response
{
  "compatible": false,
  "warning": {
    "source": "Cennini, c.1390",
    "text": "mortal enemies in everything",
    "medium": "oil",
    "effect": "accelerated darkening"
  }
}

/specify — Room specification

/archives — Archive list

/palette — Palette extraction

/health

MCP Server

The MCP server at /mcp exposes all ten Colour Memory tools as native MCP tool definitions. Any MCP-compatible orchestration layer — Claude, Cursor, LangChain, or a custom agent — can add the server URL and call every tool without custom integration code.

Setup in Claude Desktop

{
  "mcpServers": {
    "colour-memory": {
      "type":    "sse",
      "url":     "https://colour-memory-api-production.up.railway.app/mcp",
      "headers": {
        "X-API-Key": "YOUR_KEY"
      }
    }
  }
}

Restart Claude Desktop. The tools appear in Claude's tool list automatically.

MCP Tools

Response schema

All /match and /colour responses return this structure:

{
  "name":        string,         // Archive colour name
  "hex":         string,         // Hex value of archive entry
  "archive":    string,         // Source archive name
  "integrity":  "Pigment"|"Dye"|"Lake",
  "lab":        [L, a, b],       // CIE Lab D65
  "lrv":        number,         // Light Reflectance Value 0-100
  "confidence": number,         // Match confidence 0-1
  "gamut": {
    "srgb_risk":  boolean,
    "p3_safe":    boolean,
    "cmyk_risk":  boolean
  },
  "wcag": {
    "on_white":        string,    // "AA"|"AA large"|"AAA"|"fail"
    "on_black":        string,
    "contrast_white":  number,
    "contrast_black":  number
  },
  "cb_sim": {
    "deuteranopia":  string,    // Shifted hex value
    "protanopia":    string,
    "tritanopia":    string
  },
  "illuminant": {
    "tungsten":   string,         // Bradford-shifted hex
    "led_warm":   string,
    "led_cool":   string
  },
  "provenance":  string|null,   // Historical source text
  "warning":     string|null    // Cultural or regulatory flag
}

Error codes

Changelog