Palettes

Palette object

All palette endpoints return objects with this shape:

Field	Type	Description
`colors`	string[]	Array of hex color codes, lowercase, no # prefix. e.g. `["1e3a5f", "4a7fa7"]`
`info`	object \| null	Enrichment data. Null if the palette is not published (e.g. freshly generated with no DB match).
`info.name`	string	Human-readable palette name. e.g. "Harbor Dusk"
`info.tagline`	string	One-sentence description. e.g. "A coastal evening palette with steel blues fading into warm sand."
`info.slug`	string	URL-safe identifier. Used in `/palette/:slug` lookups and page URLs.
`info.tags`	string[]	Descriptive tags. e.g. `["warm", "coastal", "blue"]`
`stats`	object	Always present.
`stats.save_count`	number	Number of users who saved this palette. 0 if not in the database.
`links`	object	Always present.
`links.page`	string \| null	URL to the palette's public page on instantgradient.com. Null if not published.
`links.generator`	string	URL that opens the generator pre-loaded with these colors.

`GET /v1/palette/generate`

Generate a harmonious palette using the same algorithm as the editor. 1 credit.

If the generated colors match a published palette in the database (same color hash), the response includes full enrichment data in info. Otherwise info is null.

Parameters

Param	Type	Default	Description
`size`	int	5	Number of colors (2-8). Must be an integer.

Example

curl "https://instantgradient.com/api/v1/palette/generate?size=5" \
  -H "Authorization: Bearer ig_your_key"

Response

{
  "data": {
    "colors": [
      "1e3a5f",
      "4a7fa7",
      "aecbd6",
      "f4d7b5",
      "e8926b"
    ],
    "info": {
      "name": "Harbor Dusk",
      "tagline": "A coastal evening palette with steel blues fading into warm sand.",
      "slug": "harbor-dusk",
      "tags": [
        "warm",
        "coastal",
        "blue"
      ]
    },
    "stats": {
      "save_count": 42
    },
    "links": {
      "page": "https://instantgradient.com/palette/harbor-dusk",
      "generator": "https://instantgradient.com/app/1e3a5f-4a7fa7-aecbd6-f4d7b5-e8926b"
    }
  },
  "meta": {
    "request_id": "req_abc123def456",
    "api_version": "v1",
    "credits_used": 1,
    "credits_remaining": 494,
    "daily_limit": 500
  }
}

`GET /v1/palette/:slug`

Look up a single published palette by its slug. 1 credit.

Returns 404 if the slug does not exist or the palette is not published. The response is the same palette object shape as above, always fully populated.

Example

curl "https://instantgradient.com/api/v1/palette/harbor-dusk" \
  -H "Authorization: Bearer ig_your_key"

`GET /v1/palettes`

Browse published community palettes. 1 credit per item returned.

If you request more items than you have credits remaining, the response is truncated and pagination.truncated is set to true. See Rate Limits.

Parameters

Param	Type	Default	Description
`sort`	string	`popular`	`popular` (by save count) or `recent` (by publish date)
`tags`	string	-	Comma-separated tag filter (OR logic). e.g. `tags=warm,pastel`
`limit`	int	10	Results per page (1-50)
`offset`	int	0	Pagination offset

Pagination

Field	Type	Description
`total`	number	Total matching palettes across all pages.
`limit`	number	The limit you requested.
`offset`	number	Current offset.
`returned`	number	Actual number of items in this response (may be less than limit).
`truncated`	boolean	True if the response was truncated due to insufficient credits.
`truncated_reason`	string	Present when truncated. Value: `"credit_limit"`.

Example

curl "https://instantgradient.com/api/v1/palettes?tags=warm,pastel&sort=popular&limit=5" \
  -H "Authorization: Bearer ig_your_key"