# Gradient API
> Generate colour gradients and colour scales programmatically. Produce an evenly-spaced scale of N colours between two or more stops (interpolated in a perceptually smooth colour space — lab, lch, oklab, oklch — or plain rgb/hsl), get a single interpolated colour at any position between two colours, and build a ready-to-paste CSS gradient string (linear with any angle, or radial) from a list of stops. Colours accept hex (#f00, #ff0000) or CSS names (red, steelblue). Perfect for data-visualisation colour ramps, heatmaps, chart palettes, theme generation and UI backgrounds. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. Distinct from colour conversion / harmonious palettes (one base colour) and image palette extraction.

## 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/gradient-api/..."
```

## Pricing
- **Free** (Free) — 1,000 calls/Mo, 2 req/s
- **Starter** ($2/Mo) — 8,500 calls/Mo, 8 req/s
- **Pro** ($21/Mo) — 137,000 calls/Mo, 20 req/s
- **Mega** ($57/Mo) — 705,000 calls/Mo, 50 req/s

## Endpoints

### Gradient

#### `GET /v1/css` — Build a CSS gradient string

**Parameters:**
- `colors` (query, required, string) — Comma-separated stops Example: `#ff0000,#00ff00,#0000ff`
- `type` (query, optional, string) — linear|radial (default linear) Example: `linear`
- `angle` (query, optional, string) — Angle in degrees for linear (default 90) Example: `45`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gradient-api/v1/css?colors=%23ff0000%2C%2300ff00%2C%230000ff&type=linear&angle=45"
```

**Response:**
```json
{
    "data": {
        "css": "linear-gradient(45deg, #ff0000 0%, #00ff00 50%, #0000ff 100%)",
        "type": "linear",
        "angle": 45,
        "stops": [
            "#ff0000 0%",
            "#00ff00 50%",
            "#0000ff 100%"
        ]
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:48.368Z",
        "request_id": "f094b430-959e-4e2f-8e7d-fed66867a25e"
    },
    "status": "ok",
    "message": "Build a CSS gradient",
    "success": true
}
```

#### `GET /v1/interpolate` — Interpolate between two colours

**Parameters:**
- `colors` (query, required, string) — Exactly two stops Example: `black,white`
- `t` (query, required, string) — Position 0-1 Example: `0.5`
- `mode` (query, optional, string) — Colour space (default lab) Example: `lab`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gradient-api/v1/interpolate?colors=black%2Cwhite&t=0.5&mode=lab"
```

**Response:**
```json
{
    "data": {
        "t": 0.5,
        "to": "white",
        "hex": "#777777",
        "rgb": [
            119,
            119,
            119
        ],
        "from": "black",
        "mode": "lab"
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:48.468Z",
        "request_id": "ac4620cc-6edb-4fc3-942e-3f57c5602207"
    },
    "status": "ok",
    "message": "Interpolate between two colours",
    "success": true
}
```

#### `GET /v1/scale` — Generate a colour scale

**Parameters:**
- `colors` (query, required, string) — Comma-separated stops (hex or CSS names) Example: `red,yellow,green`
- `steps` (query, optional, string) — Number of colours 2-256 (default 7) Example: `5`
- `mode` (query, optional, string) — rgb|lrgb|hsl|hsv|lab|lch|oklab|oklch (default lab) Example: `lab`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gradient-api/v1/scale?colors=red%2Cyellow%2Cgreen&steps=5&mode=lab"
```

**Response:**
```json
{
    "data": {
        "mode": "lab",
        "steps": 5,
        "colors": [
            "#ff0000",
            "#ffa100",
            "#ffff00",
            "#91bf00",
            "#008000"
        ],
        "input_colors": [
            "red",
            "yellow",
            "green"
        ]
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:48.584Z",
        "request_id": "ea1c8a8e-4578-4b53-b2ad-a7d338bbfa9b"
    },
    "status": "ok",
    "message": "Generate a colour scale",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gradient-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Gradient API",
        "notes": "Interpolating in lab/lch/oklab/oklch is perceptually smoother than rgb. Colours accept hex (#rgb, #rrggbb) or CSS names.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/scale",
                "params": {
                    "mode": "rgb|lrgb|hsl|hsv|lab|lch|oklab|oklch, default lab",
                    "steps": "2-256, default 7",
                    "colors": "comma-separated stops (required)"
                },
                "returns": "array of N hex colours"
            },
            {
                "path": "/v1/interpolate",
                "params": {
                    "t": "0-1 (required)",
                    "mode": "colour space, default lab",
                    "colors": "exactly two stops (required)"
                },
                "returns": "a single interpolated colour"
            },
            {
                "path": "/v1/css",
                "params": {
                    "type": "linear|radial",
                    "angle": "degrees (linear, default 90)",
                    "colors": "comma-separated stops (required)"
                },
                "returns": "a CSS gradient string + stops"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Generate colour gradients and scales — interpolate
…(truncated, see openapi.json for full schema)
```


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