# gradientdeck API

Public HTTPS endpoint: https://gradientdeck.api.whox.ai/v1/

Documentation: https://gradientdeck.api.whox.ai/docs

OpenAPI3.1 schema: https://gradientdeck.api.whox.ai/openapi.json

JSON schemas: https://gradientdeck.api.whox.ai/schema.json

No WHOX account, API key or Dot ID is required for these public read operations.

| Operation | Arguments | Result fields |
| --- | --- | --- |
| `search` | `q` (string, optional), `theme` (string, optional), `industry` (string, optional), `font` (string, optional), `color` (string, optional), `content` (boolean, optional), `sort` (string, optional), `offset` (number, optional), `limit` (number, optional) |  |
| `design` | `slug` (string, required), `variant` (string, optional) |  |
| `instructions` | `slug` (string, required), `variant` (string, optional) |  |
| `filters` |  |  |
| `stats` |  |  |
| `export` | `q` (string, optional), `theme` (string, optional), `industry` (string, optional), `font` (string, optional), `color` (string, optional), `content` (boolean, optional), `sort` (string, optional), `offset` (number, optional), `limit` (number, optional), `variant` (string, optional) |  |

Call with GET query parameters or POST application/json. POST invokes the same read operation; it does not change the upstream site.

```sh
curl --get https://gradientdeck.api.whox.ai/v1/search
```

Responses contain `ok`, `service`, `operation`, `data`, and `meta` (source, duration, cache freshness and definition version). Errors contain `ok:false` and `error.code/message`. See openapi.json for full input, response, validation and error schemas.

Limits:60 requests/minute/client,2MiB JSON responses,128MiB static ZIP downloads. Reads use a complete local snapshot, refreshed separately; age and completeness are explicit in meta. Source rate limits are preserved and return429; unsupported or changed sources return a structured error. Credentials, account sessions and authenticated writes are not shared.

## Service guide

The complete public GradientDeck UI reference library: original compact and extended Markdown, metadata, palettes, typefaces, component/design rules, Agent Prompt Guide and Quick Start instructions. No WHOX account or API key is required. These are design references for your own interfaces; original designs belong to the referenced sites. Source attribution and SHA-256 hashes are preserved. Media links are returned but media/font files and usage licenses are not bundled.

Workflow: GET /v1/filters, search /v1/search?q=fintech&theme=dark, then fetch /v1/design?slug=hifi&variant=both or /v1/instructions?slug=hifi. Search metadata by default; content=true also searches both full Markdown documents. Pagination uses nextOffset until null; no rows are silently truncated. /v1/export returns up to 20 designs per JSON page and may return fewer to stay within the 2MiB bound; always follow nextOffset.

Direct files: /designs/{slug}/design.md and /designs/{slug}/design-extended.md. Full metadata: /library.json. All source Markdown and metadata in one downloadable ZIP: /archive.zip. See /v1/stats for current counts, completeness, retrieval time and snapshot ID.

Reads are served immediately from a complete validated local snapshot. The source index is checked every six hours. New/changed entries are fetched then; all Markdown is revalidated at least daily when the source is reachable. A failed refresh retains the previous complete snapshot, and every response exposes its actual mirroredAt/ageMs. No browser, login, private sessions or source writes are involved. The 2MiB JSON response limit remains; the static ZIP download has its own 128MiB cap. Fair use is 60 requests/minute/IP. api.json declares this native snapshot adapter; use openapi.json as the portable HTTP client schema.