Colors

Color object

All color endpoints return objects with this shape:

Field	Type	Description
`hex`	string	6-character lowercase hex code, no # prefix. e.g. `"1e3a5f"`
`name`	string	Nearest named color. e.g. "Midnight Explorer"
`family`	string	Hue family. One of: `Red`, `Orange`, `Yellow`, `Green`, `Blue`, `Purple`, `Pink`, `Gray`
`content`	object	AI-generated descriptions. Fields may be null if not yet enriched.
`content.intro`	string \| null	150-220 word introduction with character and design context.
`content.use_case`	string \| null	Where this color works best (industries, UI contexts). Not yet available for all colors.
`conversions`	object	Always present. Computed from the hex value.
`conversions.rgb`	object	`{ r, g, b }` each 0-255.
`conversions.hsl`	object	`{ h, s, l }` where h is 0-360, s and l are 0-100.
`conversions.oklch`	object	`{ l, c, h }` perceptual lightness, chroma, hue.
`links`	object	Always present.
`links.page`	string	URL to the color's info page on instantgradient.com.

`GET /v1/color/:hex`

Look up a single color by hex code (no # prefix). 1 credit.

Returns 404 if the hex is not in the database (4,900+ named colors are indexed).

Example

curl "https://instantgradient.com/api/v1/color/1e3a5f" \
  -H "Authorization: Bearer ig_your_key"

Response

{
  "data": {
    "hex": "1e3a5f",
    "name": "Midnight Explorer",
    "family": "Blue",
    "content": {
      "intro": "Midnight Explorer sits at the deep end of the blue family...",
      "use_case": null
    },
    "conversions": {
      "rgb": {
        "r": 30,
        "g": 58,
        "b": 95
      },
      "hsl": {
        "h": 214,
        "s": 52,
        "l": 25
      },
      "oklch": {
        "l": 0.32,
        "c": 0.08,
        "h": 255
      }
    },
    "links": {
      "page": "https://instantgradient.com/colors/1e3a5f"
    }
  },
  "meta": {
    "request_id": "req_abc123def456",
    "api_version": "v1",
    "credits_used": 1,
    "credits_remaining": 494,
    "daily_limit": 500
  }
}

`GET /v1/colors`

Search and browse the color database. 1 credit per item returned.

Supports filtering by name (case-insensitive substring match) and/or hue family. If you request more items than you have credits remaining, the response is truncated. See Rate Limits.

Parameters

Param	Type	Default	Description
`q`	string	-	Search by name (case-insensitive substring match)
`families`	string	-	Comma-separated families (OR logic). Values: `Red`, `Orange`, `Yellow`, `Green`, `Blue`, `Purple`, `Pink`, `Gray`
`limit`	int	10	Results per page (1-50)
`offset`	int	0	Pagination offset

Example

curl "https://instantgradient.com/api/v1/colors?families=Blue,Purple&limit=5" \
  -H "Authorization: Bearer ig_your_key"

Response

Same color object shape as above, in an array with pagination. See the Palettes page for the pagination object fields (they are identical).