API Documentation — ColorPeek

Authentication

Pass your API key via the x-api-key header or key query parameter.

curl "https://colorpeek.grabshot.dev/v1/extract?url=https://example.com" \
  -H "x-api-key: cp_your_api_key"

Endpoints

GET /v1/extract

Extract dominant colors from a website URL. We screenshot the page and analyze the colors.

Parameters

Param	Type	Required	Description
`url`	string	Yes	Website URL to extract colors from
`count`	integer	No	Number of colors to return (1-20, default: 5)

Example

curl "https://colorpeek.grabshot.dev/v1/extract?url=https://stripe.com&count=5" \
  -H "x-api-key: cp_your_key"

Response

{
  "success": true,
  "url": "https://stripe.com",
  "colors": [
    {
      "hex": "#0A2540",
      "rgb": { "r": 10, "g": 37, "b": 64 },
      "hsl": { "h": 210, "s": 73, "l": 15 },
      "name": "MidnightBlue",
      "percentage": 45.2
    }
  ],
  "count": 5
}

GET /v1/extract/image

Extract dominant colors directly from an image URL.

Parameters

Param	Type	Required	Description
`url`	string	Yes	Direct image URL (JPG, PNG, WebP)
`count`	integer	No	Number of colors (1-20, default: 5)

curl "https://colorpeek.grabshot.dev/v1/extract/image?url=https://example.com/photo.jpg&count=5" \
  -H "x-api-key: cp_your_key"

GET /v1/palette

Generate color palette suggestions (complementary, analogous, triadic, split-complementary, shades) from a hex color.

Parameters

Param	Type	Required	Description
`hex`	string	Yes	6-digit hex color (e.g. FF5733)

curl "https://colorpeek.grabshot.dev/v1/palette?hex=FF5733" \
  -H "x-api-key: cp_your_key"

GET /v1/health

Health check endpoint. No authentication required.

curl "https://colorpeek.grabshot.dev/v1/health"

Code Examples

Node.js

const res = await fetch(
  'https://colorpeek.grabshot.dev/v1/extract?url=https://stripe.com&count=5',
  { headers: { 'x-api-key': 'cp_your_key' } }
);
const data = await res.json();
console.log(data.colors);

Python

import requests

resp = requests.get(
    'https://colorpeek.grabshot.dev/v1/extract',
    params={'url': 'https://stripe.com', 'count': 5},
    headers={'x-api-key': 'cp_your_key'}
)
print(resp.json()['colors'])

cURL

curl "https://colorpeek.grabshot.dev/v1/extract?url=https://stripe.com&count=5" \
  -H "x-api-key: cp_your_key"

Rate Limits

Plan	Monthly Limit	Rate Limit
Free	100 requests	10/min
Starter ($9/mo)	1,000 requests	30/min
Pro ($29/mo)	5,000 requests	60/min
Business ($79/mo)	25,000 requests	120/min