API Reference
Design. Customize. Export Stunning Gradients.
Programmatic access to ChromaFlow’s gradient engine, preset library, and export pipelines. Built for developers who need reliable, versioned REST endpoints for custom design workflows.
Generate API Key View SDKs & LibrariesAuthentication
All requests to the ChromaFlow API require a valid Bearer token. Tokens are generated from your developer dashboard and expire after 90 days unless refreshed via the /auth/rotate endpoint.
Headers
Include Authorization: Bearer YOUR_API_KEY and Content-Type: application/json on every request. Missing or invalid tokens return a 401 Unauthorized response.
Rate Limits
Free tier: 100 requests/hour. Pro tier: 5,000 requests/hour. Enterprise: Custom limits with dedicated load balancers. Exceeding limits triggers a 429 Too Many Requests with a Retry-After header.
Endpoints
Access the full gradient generation pipeline, preset management, and export utilities through versioned REST routes under https://api.chromaflow.dev/v2/.
/presets
Retrieve curated gradient presets. Supports filtering by color space (sRGB, P3, OKLCH), direction, and stop count. Returns paginated JSON with metadata including author, license, and hex/RGB values.
/gradients/generate
Create custom gradients programmatically. Accepts an array of color stops, interpolation mode (linear, radial, conic), and output format. Returns a unique gradient ID and preview URLs for SVG, PNG, and CSS.
/gradients/{id}/save
Persist a generated gradient to your workspace. Supports tagging, versioning, and team sharing. Requires write permissions on the target project. Returns the saved object with a permanent URL.
/export/{id}/formats
Download gradient assets in multiple formats. Supports CSS variables, Tailwind config, Figma plugin JSON, and 4K PNG tiles. Specify resolution and compression level via query parameters.
Response Examples
Every endpoint returns consistent JSON structures with status codes, timestamps, and detailed payload objects. Below are representative responses for common operations.
Success: 200 OK
{"status": "success", "timestamp": "2024-11-12T08:14:32Z", "data": {"gradient_id": "gf_8x9k2m", "stops": [{"color": "#FF6B6B", "position": 0}, {"color": "#4ECDC4", "position": 1}], "format": "linear", "preview_url": "https://cdn.chromaflow.dev/gf_8x9k2m.png"}}
Validation Error: 422 Unprocessable
{"status": "error", "code": "INVALID_STOP_COUNT", "message": "Gradient requires between 2 and 8 color stops.", "details": {"field": "stops", "received": 1, "expected": "2-8"}}
Rate Limited: 429 Too Many Requests
{"status": "error", "code": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded your hourly request quota.", "retry_after": 1842, "documentation_url": "https://docs.chromaflow.dev/rate-limits"}