# Grabient

> Grabient is a free CSS gradient generator and color palette library at https://grabient.com. A palette is 2 to 8 OKLCH keyframes held in a short seed, and the seed is the palette's address. An agent can search palettes by words, colors or a seed, read any palette as JSON, Markdown, CSS, SVG, PNG or a swatch file design apps import, and give a person a permanent link that opens in the editor, with no key and no sign-in. The MCP server makes, changes and saves palettes for a person signed in with a free Grabient account.

The data, Markdown and image routes are plain GET requests with CORS enabled. In the patterns below, replace `{seed}`, `{slug}` and `{query}`. A seed looks like `kS7Q8Yy5S_SChv0`. A collection's address is a slug such as `ocean-gradients`, and the collections list returns the real ones.

## When to use Grabient

- A person asks for a gradient, a color palette or a background: a hero section, a card, a chart ramp, a wallpaper, social art.
- A person names a color, a mood, a season or a subject instead of exact colors: warm sunset, muted earth tones, pastel, ocean. Search answers these, and collections group palettes by subject.
- A person has brand colors as hex codes. Search finds the palettes nearest them, and the MCP server makes a palette from them.
- A person wants a palette changed: lighter, darker, calmer, more vivid, warmer, cooler, reversed, or with fewer or more colors. The MCP server makes each change as a new seed with its own permanent address.
- You need the same colors every time. A seed always renders the same palette, and no model takes part in the colors.
- You need an image of a gradient at a size you choose, without a headless browser.

Grabient's colors are for screens: it has no print inks, paint or thread, and takes no colors from an image. To read many palettes use the JSON routes, not the HTML pages.

## Read one palette

- [Palette as JSON](https://grabient.com/kS7Q8Yy5S_SChv0.json): seed, keyframes, hex colors, each color's name and the contrast of text on it, CSS in hex and OKLCH, and links to its page, files and card. Pattern: `https://grabient.com/{seed}.json`
- [Palette as Markdown](https://grabient.com/kS7Q8Yy5S_SChv0.md): the same facts as text, with the collections that hold it. Pattern: `https://grabient.com/{seed}.md`
- [Palette as PNG](https://grabient.com/kS7Q8Yy5S_SChv0.png): the gradient alone, no logo, 1200 by 630 unless asked. Takes `w` and `h`, or `size` (`1200x630`), up to 2,400 pixels a side and 3 million pixels in all; a larger size comes smaller at the same shape. Pattern: `https://grabient.com/{seed}.png`
- [Palette as SVG](https://grabient.com/kS7Q8Yy5S_SChv0.svg): the gradient as a vector, 800 by 400 unless asked. Takes `w` and `h`, or `size`, 40 to 6000 a side. Pattern: `https://grabient.com/{seed}.svg`
- [Palette as CSS](https://grabient.com/kS7Q8Yy5S_SChv0.css): CSS that works as it is: linked or pasted into a page, it fills the page with the palette. Pattern: `https://grabient.com/{seed}.css`
- [Palette as ASE](https://grabient.com/kS7Q8Yy5S_SChv0.ase): Adobe Swatch Exchange, the view's colors, for Photoshop, Illustrator, InDesign, Procreate and Affinity. Pattern: `https://grabient.com/{seed}.ase`
- [Palette as GPL](https://grabient.com/kS7Q8Yy5S_SChv0.gpl): a GIMP palette of the view's colors, for GIMP, Inkscape, Krita and Aseprite. Pattern: `https://grabient.com/{seed}.gpl`
- [Palette as GRD](https://grabient.com/kS7Q8Yy5S_SChv0.grd): the view's gradient as a Photoshop gradient. Pattern: `https://grabient.com/{seed}.grd`
- [Palette as design tokens](https://grabient.com/kS7Q8Yy5S_SChv0.tokens.json): the view's colors as DTCG design tokens, which Figma imports as variables. Pattern: `https://grabient.com/{seed}.tokens.json`
- [Palette social card](https://grabient.com/api/og?seed=kS7Q8Yy5S_SChv0): 1200 by 630 with the Grabient wordmark. Pattern: `https://grabient.com/api/og?seed={seed}`
- [Palette in the editor](https://grabient.com/kS7Q8Yy5S_SChv0): the page to give a person. Pattern: `https://grabient.com/{seed}`

Every palette route takes `style`, `steps` and `angle`.

## Find palettes

- [Search as JSON](https://grabient.com/api/search.json?query=sunset&limit=24): words, hex codes or a seed. Pattern: `https://grabient.com/api/search.json?query={query}&limit=24`
- [Search page](https://grabient.com/palettes?q=sunset): the same search for a person. Pattern: `https://grabient.com/palettes?q={query}`
- [Search as one image](https://grabient.com/palettes/sunset.png): the nine palettes its page shows first. Pattern: `https://grabient.com/palettes/{query}.png`
- [The home page as JSON](https://grabient.com/api/hot?page=1): the Hot feed, palettes and collections in one, by what was liked lately and what is new
- [The gallery as JSON](https://grabient.com/api/palettes?sort=popular&page=1&limit=24): the most liked first, or `sort` rising or newest

## Collections

- [Collections as JSON](https://grabient.com/api/collections?sort=popular&page=1&limit=24): public collections with their titles, descriptions, tags and first palettes. Add `q={query}` to search them.
- [Collections page](https://grabient.com/collections): the same list for a person
- One collection as JSON: `https://grabient.com/api/collections/{slug}`, each palette with the title and description its collection gives it, where it gives any
- One collection as Markdown: `https://grabient.com/{slug}.md`
- One collection as ASE, a group to each palette: `https://grabient.com/{slug}.ase`
- One collection as GPL: `https://grabient.com/{slug}.gpl`
- One collection as GRD, a gradient to each palette: `https://grabient.com/{slug}.grd`
- One collection as design tokens, a group to each palette: `https://grabient.com/{slug}.tokens.json`
- One collection as an image, the nine palettes its page shows first: `https://grabient.com/api/png/collection?slug={slug}`, and `https://grabient.com/api/og/collection?slug={slug}` for the card with the wordmark
- One collection's page: `https://grabient.com/{slug}`

## Tools for agents

- [MCP server](https://grabient.com/mcp): Streamable HTTP, JSON-RPC over POST, for a free Grabient account: the app signs the person in once through OAuth 2.1 when it is added. Tools: get_account, search_palettes, search_collections, get_collection, compose_palette, adjust_palette, inspect_palettes, show_palettes, list_saved_palettes, save_palette, list_my_collections, save_collection, delete_collection. [How to connect](https://grabient.com/mcp-server).
- [MCP server card](https://grabient.com/mcp/server-card): the server's name, address and protocol versions as JSON
- [Agent catalog](https://grabient.com/.well-known/ai-catalog.json): the AI Catalog entry that leads to the card

## Optional

- [Full reference](https://grabient.com/llms-full.txt): the palette model, what the routes take and return, the tools, limits and redirects
- [About Grabient](https://grabient.com/about): how the palettes are made
- [Sitemap](https://grabient.com/sitemap.xml): pages, searches, collections and palettes

## The palette model

Seeds start with k and encode 2 to 8 OKLCH keyframes. Each keyframe is {l,c,h}: lightness 0 to 1, chroma 0 to 0.35, and hue in degrees. Hue is unwrapped: 210 then 570 describes a full clockwise turn. Adjacent keyframes may differ by at most 540 degrees. A Catmull-Rom spline joins the keyframes, lightness is clamped, and chroma is reduced at constant lightness and hue until the color fits sRGB.

The seed is the palette. Style, steps, angle and size choose how it is drawn and are never part of its identity. The default style is linearGradient, with 7 steps at 90 degrees. Steps run from 3 to 100, and never fewer than the palette has keyframes. The six styles are linearGradient, linearSwatches, radialGradient, radialSwatches, angularGradient and angularSwatches. Gradient styles interpolate the sampled stops. Swatch styles draw equal hard bands. Size is `WxH` in pixels; either side may be `auto`, which follows the other at the file's default shape.

A seed comes from an answer or a link: one typed or changed by hand is another palette, or none. To make a palette, a connected app calls the MCP tool compose_palette with hex colors, and a person opens the editor. Making one saves nothing.

## Routes in detail

Unknown query parameters are ignored.

| Route | Returns |
| --- | --- |
| `/{seed}.json` | {model, seed, kseed, name, spec, style, steps, angle, classes, kinds, harmony, colors, names, contrast:{text,ratios,ends}, p3, css:{hex,oklch}, url, links}. `name` and `names` are what most people call the palette and each color |
| `/{seed}.png` | PNG without a logo, 1200 by 630 by default. `w` and `h`, which come first, or `size=WxH`; up to 2,400 a side and 3,024,000 pixels, a larger size drawn smaller at its shape |
| `/{seed}.svg` | SVG, 800 by 400 by default. `w` and `h`, which come first, or `size=WxH`; 40 to 6000 a side |
| `/{seed}.css` | CSS that works as it is: linked or pasted into a page, it fills the page with the palette, with a Display-P3 version where a P3 screen shows more. Colors in OKLCH, or with `colors=hex`, `rgb` or `hsl` |
| `/{seed}.ase` | Adobe Swatch Exchange: a group named for the palette, an RGB color to each of the view's colors |
| `/{seed}.gpl` | A GIMP palette of the view's colors |
| `/{seed}.grd` | The view's gradient as a Photoshop gradient |
| `/{seed}.tokens.json` | The view's colors as design tokens (DTCG 2025.10), a color token to each |
| `/{slug}.ase`, `.gpl`, `.grd`, `.tokens.json` | A public collection's palettes in one file, each in the view it was saved in |
| `/api/og?seed={seed}` | 1200 by 630 card with the wordmark and each color's hex |
| `/api/search.json?query={query}&limit=48&sort=popular` | {query, items, tier, read}: 1 to 96 items, each with `kseed`, its view, `likes`, `score` and, on the palettes every `sort` puts first, `lead`, and no colors, which `/{kseed}.json` has. `sort` is popular, rising, newest or oldest |
| `/api/og/query?query={query}` | A search's image as a card with the wordmark |
| `/api/palettes?sort=popular&page=1&limit=24` | The gallery: {items, total, page, limit, totalPages}. `sort` is popular, rising, newest or oldest; with rising, `frame` is 1w (the default), 3m or 1y, how long a like counts |
| `/api/collections?q={query}&sort=popular&page=1&limit=24` | Public collections: {items, total, page, totalPages}. `sort=rising` takes `frame` as the gallery does |
| `/api/hot?page=1` | The home page: {page, palettes, collections}, the twenty-four hottest palettes and a page of the hot collections |
| `/api/hot?q={query}&page=1` | The home page searched: {page, query, palettes, collections, tier}, sixty palettes that answer the words, the ones that carry `lead` first and then the most liked, and a page of the collections that answer them |
| `/`, `/palettes`, `/palettes/rising`, `/collections`, `/collections/rising` | The home page and the lists for a person. Rising is the week's |
| `/palettes?q={query}`, `/collections?q={query}`, `/?q={query}` | Search pages for a person: palettes, collections, or both |
| `/random` | Redirects to a new random palette |

## Search

Words, emoji, hex codes and seeds are answered from a snapshot of every public palette, with no model call. Words cover colors, tones, moods, scenes, seasons and uses in 20 languages, and a few hundred emoji stand for them. Hex codes find the palettes nearest those colors, and a seed the palettes most like it, led by up to six that its public collections hold. Names no color says, such as a team or a game, are found in palettes' titles, the ones their collections give them among them, in collections' titles and tags, and in the names those collections' descriptions of a palette write, in one of them or across them (tier "named"). Other words outside the vocabulary, in any language, are read by an embedding model once per distinct query (tier "model"); past its limit the answer is tier "account" with no palettes. `read` says what the search made of the words: the phrases it knew, the words nothing read, and what followed no, not or without, which a search cannot leave out. A search for a collection's own subject is led by that collection's palettes. The palettes a search's words name and a seed's collection-mates carry `lead`, and every `sort` puts them first.

## MCP

POST JSON-RPC 2.0 to https://grabient.com/mcp with Content-Type application/json and an access token: one request a POST, no session. Protocol 2026-07-28, and the initialize handshake of 2025-11-25, 2025-06-18, 2025-03-26. Every request needs the token. Without one the server answers 401 with a WWW-Authenticate challenge that names https://grabient.com/.well-known/oauth-protected-resource/mcp, and the app signs the person in once through OAuth 2.1, identifying itself with its published client metadata document or registering itself.

A tool answers one text block of JSON. A palette in it is a card: {seed, url, title, colors, style, steps, angle}, where `colors` are the bands a Swatches view draws (past 12, the ones nearest its own colors), and for a gradient the colors it blends between. One made, changed or inspected also has `css` (up to 32 steps) and a `note` when something needs saying, and for an app that draws no view of Grabient's, `files` (its PNG, SVG and CSS addresses and its card). The server also serves a skill, a one-page guide for a model, at `skill://grabient/SKILL.md`. Tools:

- `get_account`: The Grabient account this connection keeps color palettes and collections in: its name and username. It also says how many palettes it has saved, how many collections it keeps, and where its Saved page is.
- `search_palettes`: Search Grabient's gallery of color palettes and gradients by color, mood, theme or brand colors, or browse its popular, rising, newest and hot ones. `query` takes words in any language, hex codes, or a palette's seed or address for palettes like it. `colors` takes up to 5 hex colors the palettes come near. With neither, `order` lists the gallery. `read` gives the `words` understood and the ones `notRead`, and `page` reads on to `total`.
- `search_collections`: Search Grabient's public collections of color palettes and gradients by theme or use, or list the most popular. Each is an ordered list of up to 100 palettes with a title, a description and tags. `first` is the addresses of its first six, each in its view there.
- `get_collection`: Read one collection of color palettes and gradients in order, each palette with its colors and view. A public collection or one of the account's own, by its slug or its address. A palette it names is `named`, with any `description`. `total` counts its palettes, which `page` reads on.
- `compose_palette`: Make color palettes and CSS gradients from 2 to 8 hex colors each, such as brand colors, in order. Each comes with its seed, its address, its colors and the CSS that draws it as Grabient does in the view given: `colors` are the bands a Swatches view draws, else the colors a gradient blends between. Steps left out show every color. Nothing is saved. Each color is held as its hex.
- `adjust_palette`: Change a color palette or gradient from its seed: lighter, darker, calmer, more vivid, warmer, cooler, reversed, or with fewer or more colors. Each of `variants` makes one new palette, its fields applied together, and `hold` keeps colors such as a brand color as they are. Nothing is saved. `from` is the palette asked about, and a `note` says what a change could not reach.
- `inspect_palettes`: Read color palettes in full, up to 12: each color's hex, its name and its WCAG 2 contrast on white and on black, with the CSS. Each is read in the view given, else the one Grabient shows it in: the colors of a Swatches view are its bands, and of a gradient the ones it blends between. `gallery` is null for a palette the gallery lacks, `collections` are the public ones that hold it, and `credit` names who brought it.
- `show_palettes`: Show color palettes and gradients side by side as numbered tiles, up to 24, each in the view given, else the one Grabient shows it in. One palette may come in several views. An app that draws Grabient's view shows each with its colors, and copies its address, CSS, SVG or PNG in full screen; in any other, each tile has `png`, its picture's address. `own` marks a title given or written for the palette on Grabient; any other names its colors.
- `list_saved_palettes`: The color palettes and gradients saved to the Grabient account, newest first, each in the view it was saved in. `total` counts them all, and `next` reads on from the last. `named` marks a title the account gave; any other is its title on Grabient. `savedPage` is the page that lists them.
- `save_palette`: Save a color palette or gradient to the Grabient account in the view given, else the one Grabient shows it in, or take it out with `saved` false. The first save of a palette new to Grabient adds it to the public gallery, where anyone can find it, without the account's name unless it opted in: `published` says so. A palette saved before keeps its first view. `title` is the account's own name for it, shown to nobody else.
- `list_my_collections`: The Grabient account's own collections of color palettes and gradients, latest change first, each with its `visibility`: only the account sees a private one, and everyone a public one. An account keeps up to 200.
- `save_collection`: Make a private collection of color palettes, such as a brand's colors or a theme's gradients, or change one of the account's own, which everyone sees at once when it is public. Without a slug it makes one from a title and 1 to 100 palettes. With a slug a field given replaces what is there: `palettes` the whole list in order. `remove` takes palettes out and `add` puts them at the end. A palette may carry its own `title` and `description` here.
- `delete_collection`: Delete one of the Grabient account's own collections of color palettes, a public one from the site too. Its palettes stay wherever else they are. This cannot be undone.

## Redirects and old addresses

Addresses from the earlier Grabient keep working. A seed that starts with an underscore redirects to its keyframe seed when the stored migration knows it. `/palettes/{words}` redirects to `/palettes?q={words}`. `/{seed}/edit` redirects to `/{seed}`.

## Limits

A read a cache holds is never counted. Past a limit the answer is HTTP 429 with Retry-After, and an MCP tool says the limit and the wait in words.

- A list or a search: 60 a minute for an address.
- Words outside the vocabulary: 20 new queries a minute and 300 a day, for an address or for an account through MCP.
- A PNG: 60 a minute for an address. One of more pixels than 1200 by 630 shares 2,000 a day with the whole site. SVG, CSS, JSON and Markdown are never counted.
- MCP tool calls: 120 a minute and 5,000 a day for an account.
- A search takes 100 characters and answers 96 palettes at most.