API

Generate color palettes programmatically. Integrate SwatchSmith into your tools, workflows, and AI agents.

Quick Start

Send a POST request with a hex color to get a full palette back in seconds.

curl -X POST https://swatchsmith.dev/api/v1/palette \
  -H "Authorization: Bearer ss_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"color": "#52b788", "scheme": "mono", "variation": "default"}'

Authentication

All API requests require a Bearer token in the Authorization header. You can create and manage API keys from your profile or the section below.

Authorization: Bearer ss_your_api_key

Endpoint Reference

POST/api/v1/palette

Parameters

color

required

Hex color value (e.g. "#52b788").

scheme

optional

Palette scheme. One of mono, contrast, triade, tetrade, analogic.

Default: mono

variation

optional

Color variation. One of default, pastel, soft, light, hard, pale.

Default: default

Example Request

curl -X POST https://swatchsmith.dev/api/v1/palette \
  -H "Authorization: Bearer ss_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"color": "#52b788", "scheme": "mono", "variation": "default"}'

Example Response

{
  "base_color": { "hex": "#52b788", "name": "Ocean Green" },
  "scheme": "mono",
  "variation": "default",
  "colors": [
    { "hex": "#3a8162", "name": "Amazon", "text_color": "#ffffff" },
    { "hex": "#52b788", "name": "Ocean Green", "text_color": "#000000" },
    { "hex": "#74c69d", "name": "Silver Tree", "text_color": "#000000" },
    { "hex": "#95d5b2", "name": "Vista Blue", "text_color": "#000000" }
  ]
}

API Keys

Rate Limits & Usage

Pro

100 requests per minute per API key. Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining.

Need higher limits? Reach out at hello@swatchsmith.dev.

WCAG Contrast Data

Every color in the API response now includes WCAG accessibility data:

{
  "hex": "#3a8162",
  "name": "Amazon",
  "text_color": "#ffffff",
  "contrast_ratio": 4.7,
  "wcag_aa": true,
  "wcag_aaa": false
}