# Color API
> A complete colour toolkit — convert between hex, RGB, HSL, HSV and CMYK with relative luminance, generate harmonious palettes (complementary, triadic, tetradic, analogous, monochromatic, shades), and compute WCAG contrast ratios with AA/AAA pass-fail for accessibility. Server-side, instant, no third-party services.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/color-api/..."
```

## Pricing
- **Free** (Free) — 12,000 calls/Mo, 3 req/s
- **Basic** ($6/Mo) — 150,000 calls/Mo, 12 req/s
- **Pro** ($18/Mo) — 750,000 calls/Mo, 35 req/s
- **Mega** ($44/Mo) — 3,000,000 calls/Mo, 90 req/s

## Endpoints

### Color

#### `GET /v1/contrast` — WCAG contrast ratio

**Parameters:**
- `fg` (query, required, string) — Foreground colour Example: `ffffff`
- `bg` (query, required, string) — Background colour Example: `777777`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/color-api/v1/contrast?fg=ffffff&bg=777777"
```

**Response:**
```json
{
    "data": {
        "wcag": {
            "aa_large": true,
            "aa_normal": false,
            "aaa_large": false,
            "aaa_normal": false
        },
        "ratio": 4.48,
        "background": "#777777",
        "foreground": "#ffffff"
    },
    "meta": {
        "timestamp": "2026-05-30T06:59:09.647Z",
        "request_id": "864579e5-ab40-4f72-9d25-99d38aa87e3f"
    },
    "status": "ok",
    "message": "Contrast computed",
    "success": true
}
```

#### `GET /v1/convert` — Convert a colour

**Parameters:**
- `color` (query, required, string) — hex / short-hex / r,g,b Example: `ff5733`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/color-api/v1/convert?color=ff5733"
```

**Response:**
```json
{
    "data": {
        "hex": "#ff5733",
        "hsl": {
            "h": 11,
            "l": 60,
            "s": 100
        },
        "hsv": {
            "h": 11,
            "s": 80,
            "v": 100
        },
        "rgb": {
            "b": 51,
            "g": 87,
            "r": 255
        },
        "cmyk": {
            "c": 0,
            "k": 0,
            "m": 66,
            "y": 80
        },
        "is_dark": true,
        "luminance": 0.2832
    },
    "meta": {
        "timestamp": "2026-05-30T06:59:09.727Z",
        "request_id": "a744b384-3e21-4e7e-bdc0-a93f1910adfe"
    },
    "status": "ok",
    "message": "Colour converted",
    "success": true
}
```

#### `GET /v1/palette` — Harmonious palette

**Parameters:**
- `color` (query, required, string) — Base colour Example: `3498db`
- `type` (query, optional, string) — analogous complementary triadic tetradic monochromatic shades Example: `triadic`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/color-api/v1/palette?color=3498db&type=triadic"
```

**Response:**
```json
{
    "data": {
        "base": "#3498db",
        "type": "triadic",
        "count": 3,
        "colors": [
            "#3398db",
            "#db3398",
            "#98db33"
        ]
    },
    "meta": {
        "timestamp": "2026-05-30T06:59:09.799Z",
        "request_id": "4b8730c3-eed5-4d18-98c4-2603a9b559f6"
    },
    "status": "ok",
    "message": "Palette generated",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/color-api
OpenAPI spec: https://www.oanor.com/api/color-api/openapi.json