Koksfabrik Image API

1. Basis-URL & Authentifizierung

Alle Endpoints liegen unter https://koksfabrik.lovable.app/api/v1. Authentifizierung erfolgt per Bearer-Token im Authorization-Header. Keys erzeugst du im Dashboard.

curl https://koksfabrik.lovable.app/api/v1/jobs \
  -H "Authorization: Bearer kx_live_••••••••••••••••" \
  -H "Accept: application/json"

2. Rate-Limits

Limits werden pro API-Key gezählt und im Response-Header übermittelt:

X-RateLimit-Limit:      600
X-RateLimit-Remaining:  587
X-RateLimit-Reset:      1717420800

Bei Überschreitung antwortet der Server mit 429 Too Many Requests und einem Retry-After-Header in Sekunden.

3. POST /v1/convert

Konvertiert ein Bild in ein Zielformat. Akzeptiert multipart/form-data oder eine öffentlich erreichbare source_url.

curl -X POST https://koksfabrik.lovable.app/api/v1/convert \
  -H "Authorization: Bearer kx_live_••••" \
  -F "file=@hero.jpg" \
  -F "format=webp" \
  -F "quality=85" \
  -F "strip_exif=true"

Antwort:

{
  "job": {
    "id": "0b0e6e9c-9b5e-4f2a-9b3b-1c2d3e4f5a6b",
    "file_name": "hero.jpg",
    "original_size": 1843200,
    "output_size": 264310,
    "output_format": "webp",
    "savings_pct": 85.66,
    "duration_ms": 412,
    "status": "ok",
    "created_at": "2026-06-03T12:34:56Z"
  },
  "download_url": "https://cdn.koksfabrik.app/d/0b0e6e9c…?sig=…&exp=1717424400"
}

4. GET /v1/jobs

Listet die letzten Conversion-Jobs des aktuellen Accounts. Pagination via ?cursor= und ?limit= (max 100).

curl "https://koksfabrik.lovable.app/api/v1/jobs?limit=20" \
  -H "Authorization: Bearer kx_live_••••"

5. POST /v1/scans

Startet einen Website-Scan: crawlt eine URL, analysiert alle Bilder, schätzt Einsparpotenzial und liefert einen LCP-Hinweis.

curl -X POST https://koksfabrik.lovable.app/api/v1/scans \
  -H "Authorization: Bearer kx_live_••••" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "depth": 1}'

{
  "scan": {
    "id": "f4c1…",
    "url": "https://example.com",
    "status": "queued",
    "images_total": 0,
    "images_optimizable": 0,
    "savings_estimate_bytes": 0,
    "lcp_image_url": null,
    "report_url": null,
    "created_at": "2026-06-03T12:35:01Z"
  }
}

6. Signed Downloads

Jeder erfolgreiche Job liefert eine signierte download_url mit Ablaufzeit (default 15 Min). Signaturen werden HMAC-SHA256 berechnet und sind gebunden an Job-ID + Ablauf:

https://cdn.koksfabrik.app/d/<job-id>?sig=<hex>&exp=<unix>

sig = HMAC_SHA256(secret,  job_id + "." + exp)

Eigene Signaturen kannst du serverseitig mit dem im Dashboard ausgegebenen signing_secret validieren — ideal, um Downloads in deiner eigenen App weiterzureichen, ohne den API-Key preiszugeben.

7. JSON-Schemas

conversion_job

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://koksfabrik.lovable.app/schemas/conversion_job.json",
  "title": "ConversionJob",
  "type": "object",
  "required": ["id", "file_name", "original_size", "output_size", "output_format", "savings_pct", "status", "created_at"],
  "properties": {
    "id":             { "type": "string", "format": "uuid" },
    "file_name":      { "type": "string", "minLength": 1, "maxLength": 500 },
    "original_size":  { "type": "integer", "minimum": 0 },
    "output_size":    { "type": "integer", "minimum": 0 },
    "output_format":  { "type": "string", "enum": ["webp", "avif", "jxl", "jpg", "png"] },
    "savings_pct":    { "type": "number", "minimum": 0, "maximum": 100 },
    "duration_ms":    { "type": ["integer", "null"], "minimum": 0 },
    "preset_name":    { "type": ["string", "null"], "maxLength": 120 },
    "status":         { "type": "string", "enum": ["ok", "error"] },
    "created_at":     { "type": "string", "format": "date-time" }
  }
}

website_scan

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://koksfabrik.lovable.app/schemas/website_scan.json",
  "title": "WebsiteScan",
  "type": "object",
  "required": ["id", "url", "status", "images_total", "images_optimizable", "savings_estimate_bytes", "created_at"],
  "properties": {
    "id":                       { "type": "string", "format": "uuid" },
    "url":                      { "type": "string", "format": "uri" },
    "status":                   { "type": "string", "enum": ["queued", "running", "ok", "error"] },
    "images_total":             { "type": "integer", "minimum": 0 },
    "images_optimizable":       { "type": "integer", "minimum": 0 },
    "savings_estimate_bytes":   { "type": "integer", "minimum": 0 },
    "lcp_image_url":            { "type": ["string", "null"], "format": "uri" },
    "report_url":               { "type": ["string", "null"], "format": "uri" },
    "created_at":               { "type": "string", "format": "date-time" }
  }
}

8. OpenAPI / Swagger

Die vollständige OpenAPI-3.1-Spezifikation liegt unter /api/openapi.json bereit und kann direkt in Swagger UI, Postman oder Insomnia importiert werden.

curl https://koksfabrik.lovable.app/api/openapi.json -o koksfabrik-openapi.json
# Swagger UI lokal starten:
docker run -p 8080:8080 -e SWAGGER_JSON=/spec.json \
  -v $PWD/koksfabrik-openapi.json:/spec.json swaggerapi/swagger-ui