Endpoints en Parameters

Sandbox (Test)

Gebruik kf_test_sk_ sleutels op https://api-test.kleurflow.nl/v1. Test-gradienten worden niet opgeslagen in de productie-bibliotheek en hebben geen effect op publieke collecties.

Productie (Live)

Gebruik kf_live_sk_ sleutels op https://api.kleurflow.nl/v1. Alle gegenereerde gradienten worden direct beschikbaar in je dashboard en publieke profiel. Controleer je scope-rechten voordat je schrijf-operaties uitvoert.

Webhook Notificaties

Stel een webhook-URL in voor real-time notificaties bij gradient-generatie, collectie-updates of quota-warschuwingen. KleurFlow stuurt een HMAC-SHA256 getekend POST naar je endpoint met het body-hash in de X-KleurFlow-Signature header.

POST /v1/gradients/generate

Genereer een nieuwe CSS-gradient op basis van configuratie-parameters. Accepteert body parameters: type (linear | radial | conic), angle (0–360), colors (array van 2–8 hex-waarden), stops (optioneel percentage-lijst), blendMode (normal | multiply | screen), en outputFormat (css | svg | tailwind).

Response: { data: { id, css, previewUrl, createdAt, colorPalette } }

GET /v1/gradients/{id}

Haal een specifieke gradient op met volledige metadata. Retourneert de CSS-output, gegenereerde SVG-preview, gebruiksgeschiedenis en gekoppelde collecties. Optionele query-parameter include=usage,comments voegt relaties toe.

Response: { data: { id, type, angle, colors, stops, css, svg, previewUrl, metadata } }

GET /v1/gradients

List gradients met paginate en filter-opties. Query parameters: page (default 1), limit (1–100, default 20), type (filter op gradient-type), sortBy (created_at | popular | recently_used), order (asc | desc).

Response: { data: [...], meta: { total, currentPage, lastPage, perPage }, links: { next, prev } }

POST /v1/collections

Maak een nieuwe gradient-collectie aan. Body parameters: name (string, max 120 tekens), description (string, optioneel), visibility (public | private | team), gradientIds (array, optioneel — voeg bestaande gradienten direct toe).

Response: { data: { id, name, description, visibility, gradientCount, createdAt, updatedAt } }

PUT /v1/gradients/{id}

Werk een bestaande gradient bij. Alleen eigenaar of gebruikers met full scope op het resource-account kunnen muteren. Body parameters: angle, colors, stops, blendMode — alleen opgegeven velden worden geüpdatet (partial update).

Response: { data: { id, css, previewUrl, updatedAt, changedFields } }

DELETE /v1/gradients/{id}

Verwijder een gradient definitief. Onomkeerbaar — gradient wordt verwijderd uit alle collecties en bijbehorende preview-assets worden binnen 60 seconden opgeschoond. Retourneert HTTP 204 No Content bij succes.

Response: 204 No Content

type

Type: string  |  Verplicht: ja  |  Waarden: linear, radial, conic

Bepaalt het gradient-algoritme. linear produceert een rechte overgang tussen kleurstops. radial straalt vanuit een centraal punt. conic roteert rond een middelpunt en is ideaal voor cirkelvormige UI-elementen.

angle

Type: integer  |  Verplicht: ja (voor linear/conic)  |  Bereik: 0–360

Rotatie van het gradient in graden. 0 = naar boven, 90 = naar rechts, 180 = naar beneden, 270 = naar links. Voor radial gradients wordt deze parameter genegeerd.

colors

Type: array[string]  |  Verplicht: ja  |  Lengte: 2–8  |  Formaat: hex (#RRGGBB of #RGB)

Lijst van kleurstops in volgorde van verschijning. KleurFlow accepteert zowel 3- als 6-cijferige hex-waarden. Transparantie wordt ondersteund via #RRGGBBAA (8-cijferig hex). Voorbeeld: ["#6366f1", "#a855f7", "#ec4899"].

stops

Type: array[number]  |  Verplicht: nee  |  Bereik: 0–100  |  Default: gelijkmatig verdeeld

Percentage-positie voor elke kleurstop. Als niet gespecificeerd, verdeelt KleurFlow de stops lineair over het gradient-gebied. Lengte moet overeenkomen met colors array. Voorbeeld: [0, 35, 100].

blendMode

Type: string  |  Verplicht: nee  |  Default: normal  |  Waarden: normal, multiply, screen

CSS blend-mode die wordt toegepast op de overgang tussen kleurstops. multiply produceert donzige, diepe tinten. screen verheldert de overgang. Let op: blendMode wordt alleen ondersteund in SVG-output, niet in standaard CSS-gradienten.

outputFormat

Type: string  |  Verplicht: nee  |  Default: css  |  Waarden: css, svg, tailwind

Bepaalt het output-formaat van de response. css retourneert een background: linear-gradient(...) string. svg produceert een inline SVG-data URI. tailwind genereert een Tailwind-config snippet met backgroundImage en backgroundSize properties.

400 — Bad Request

INVALID_PARAMETER — Een vereiste parameter ontbreekt of heeft een ongeldig formaat. Controleer de details.field en details.expected velden in de response voor de specifieke fout.

401 — Unauthorized

TOKEN_MISSING — Geen Authorization header verzonden.  |  TOKEN_EXPIRED — De API-sleutel is verlopen of ingetrokken.  |  TOKEN_INVALID — Ongeldig token-formaat of checksum.

403 — Forbidden

SCOPE_INSUFFICIENT — Je API-sleutel heeft read scope maar probeert een schrijf-operatie.  |  RESOURCE_LOCKED — Het resource-account heeft API-toegang uitgeschakeld.

404 — Not Found

GRADIENT_NOT_FOUND — De opgevraagde id bestaat niet of is verwijderd.  |  ENDPOINT_NOT_FOUND — Ongeldige route of API-versie.

429 — Too Many Requests

RATE_LIMIT_EXCEEDED — Je hebt het minutielijke quota overschreden. De response-header Retry-After bevat de wachttijd in seconden. Implementeer exponential backoff (start bij 2s, max 30s) voor robuuste herpogingen.

500 — Internal Server Error

GENERATION_FAILED — De gradient-engine heeft een onverwachte fout ontmoet. Dit komt voor in <0.3% van de requests. Herhaal de request met een willekeurige X-Request-Id header om debugging te versnellen.

Voorbeeld 1 — Linear Gradient Genereren

Request:

POST /v1/gradients/generate

{ "type": "linear", "angle": 135, "colors": ["#0ea5e9", "#8b5cf6", "#d946ef"], "stops": [0, 50, 100], "outputFormat": "css" }

Response (201 Created):

{ "data": { "id": "grd_8f2a1c3e9d", "css": "linear-gradient(135deg, #0ea5e9 0%, #8b5cf6 50%, #d946ef 100%)", "previewUrl": "https://cdn.kleurflow.nl/previews/grd_8f2a1c3e9d.png", "createdAt": "2024-11-15T14:32:07Z", "colorPalette": ["#0ea5e9", "#8b5cf6", "#d946ef"] } }

Voorbeeld 2 — Gradient Lijsten met Filter

Request:

GET /v1/gradients?type=radial&sortBy=popular&order=desc&limit=5

Response (200 OK):

{ "data": [{ "id": "grd_4b7c2d1a", "type": "radial", "colors": ["#f43f5e", "#fbbf24"], "previewUrl": "..." }, ...], "meta": { "total": 847, "currentPage": 1, "lastPage": 170, "perPage": 5 }, "links": { "next": "/v1/gradients?type=radial&page=2" } }

Voorbeeld 3 — Collectie Aanmaken

Request:

POST /v1/collections

{ "name": "Herenigma UI — Q4 2024", "description": "Gradienten voor het nieuwe design systeem van Herenigma. Inclusief donkere en lichte varianten.", "visibility": "team", "gradientIds": ["grd_8f2a1c3e9d", "grd_4b7c2d1a", "grd_9e1f3a5c"] }

Response (201 Created):

{ "data": { "id": "col_3d8f2a1b", "name": "Herenigma UI — Q4 2024", "visibility": "team", "gradientCount": 3, "createdAt": "2024-11-15T14:45:22Z" } }