Marken-Asset-API

Quickstart

1. API-Key bei den Plattform-Administratoren anfordern (Bereich „API-Zugänge“). Der Key gehört auf Ihren Server, nie in ausgelieferten Browser-Code.
2. Authentifizieren: Header Authorization: Bearer <key> — für <img>-URLs alternativ ?api_key=<key>.
3. Request: GET /api/public/v1/{brand}/{asset-key}. Marke wechseln = Slug tauschen.

curl "https://brand.co-red.de/api/public/v1/waz/logo-farbig" \
  -H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx"

{
  "data": {
    "key": "logo-farbig",
    "brand": "waz",
    "files": { "svg": { "url": "https://…/logo.svg?v=8f2a1c9e" } }
  }
}

const logo = (brand) =>
  `https://brand.co-red.de/api/public/v1/${brand}/logo-farbig.svg?api_key=${KEY}`;

<img src={logo("waz")} alt="WAZ" />
<img src={logo("nrz")} alt="NRZ" />

Konsole

Key eintragen, Marke und Endpunkt wählen, senden. Der Key bleibt im Browser-Tab und wird nicht gespeichert.

Asset-Keys

Die Liste ist die Live-Antwort von GET /api/public/v1/{brand} für die gewählte Marke – alle Schlüssel, die der Key dort sieht. Klick kopiert den Key.

Endpunkte

Basis-URL: https://brand.co-red.de/api/public/v1 — alle Endpunkte sind reine Lesezugriffe (GET). Details bei Bedarf aufklappen.

Farben für Digital und Print

curl "https://brand.co-red.de/api/public/v1/waz/colors" \
  -H "Authorization: Bearer bp_live_…"

// Nur Bildschirmfarben oder nur Druckangaben:
GET /api/public/v1/waz/colors?medium=digital
GET /api/public/v1/waz/colors?medium=digital&theme=dark
GET /api/public/v1/waz/colors?medium=print

• Digital: HEX, RGB (0–255), HSL (Grad / Prozent) im sRGB-Farbraum unter digital.light und digital.dark. Dunkle Varianten werden nur geliefert, wenn sie hinterlegt und aktiviert sind; ihre Herkunft steht in source.
• Verläufe: gradients enthält Art, Winkel und geordnete Farbstopps mit Positionen von 0–100 %. Diese Bildschirmdefinition ist keine verbindliche Druckvorlage.
• Print: Gespeicherte CMYK-Prozentwerte sowie Pantone, HKS und RAL einschließlich aller hinterlegten Zusätze. RAL bezeichnet eine Lack-/Beschichtungsreferenz, keine CMYK-Umrechnung.
• Druckverbindlichkeit: CMYK wird nicht neu aus HEX berechnet. Bestehende Werte können im Editor automatisch entstanden sein; cmyk_source kennzeichnet sie deshalb als gespeichert, nicht profilverifiziert. icc_profile: null bedeutet: kein geprüftes Ausgabeprofil hinterlegt. Papier, Druckverfahren, ICC-Profil und Sonderfarben mit der Druckerei abstimmen; Anwendungshinweise stehen in usage.
• Fehlende Angaben: null bedeutet nicht hinterlegt. Keine stille Ersetzung durch andere Farben; theme zusammen mit medium=print liefert HTTP 400.

const response = await fetch(
  `https://brand.co-red.de/api/public/v1/${brand}/colors`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
if (!response.ok) throw new Error(`Color API: ${response.status}`);
const { data } = await response.json();
const primary = data.palettes.flatMap(p => p.colors)
  .find(color => color.category === "primary");
const hex = primary?.digital?.light?.hex;

Farbwerte im eigenen Projekt speichern und einmal täglich per ETag abgleichen. Der Asset-Manifest-Abgleich umfasst keine Farbpaletten; dafür /{brand}/colors separat prüfen. API-Schlüssel nur auf dem eigenen Server verwenden, nicht im ausgelieferten Browsercode.

Caching & Sync

Assets ändern sich selten. Nicht pro Seitenaufruf abfragen, sondern lokal cachen (Server, CDN, Build) und synchronisieren:

1. Initial-Sync: GET /manifest paginiert abrufen (next folgen, bis null) und benötigte Dateien speichern. Datei-URLs sind über ?v=… versioniert und unbegrenzt cachebar.
2. Delta-Sync (1× täglich): GET /manifest?since=<ISO-8601> liefert nur seitdem geänderte Assets. Nur diese Dateien neu laden, Zeitstempel des Laufs speichern.
3. Conditional Requests: ETag speichern und als If-None-Match mitsenden – unverändert antwortet die API mit 304 ohne Body.

const BASE = "https://brand.co-red.de/api/public/v1";
const headers = { Authorization: `Bearer ${process.env.BRAND_API_KEY}` };

export async function sync(lastRun?: string) {
  let url = `${BASE}/manifest${lastRun ? `?since=${lastRun}` : ""}`;
  const startedAt = new Date().toISOString();
  while (url) {
    const res = await fetch(url, { headers });
    if (res.status === 429) { await new Promise(r => setTimeout(r, 5000)); continue; }
    if (!res.ok) throw new Error(`Brand API ${res.status}`);
    const page = await res.json();
    for (const asset of page.data) await saveLocally(asset); // eigene Implementierung
    url = page.next ? new URL(page.next, BASE).toString() : "";
  }
  return startedAt; // als lastRun für den nächsten Lauf speichern
}

Fehler & Limits

Erfolg: JSON mit data. Fehler: einheitliches error-Objekt mit maschinenlesbarem code, message und – bei unbekannten Keys – einem hint mit ähnlichen gültigen Keys.

{
  "error": {
    "code": "not_found",
    "message": "No asset registered for key 'logo-gruen' on brand 'waz'.",
    "hint": "Meinten Sie: logo-farbig, logo-schwarz?"
  }
}

• ETag / 304: Jede JSON-Antwort enthält einen ETag. Senden Sie ihn als If-None-Match mit, erhalten Sie bei unveränderten Daten ein schlankes 304.
• Datei-URLs sind versioniert: Der Parameter ?v=… ändert sich bei jedem Austausch. Dateien dürfen daher dauerhaft (immutable) zwischengespeichert werden.
• Fallback: Mit ?fallback=1 liefert die API eine verfügbare Variante statt eines Fehlers und kennzeichnet dies im Feld fallback_from.
• Rate-Limit: Standardmäßig 600 Anfragen pro Minute und Schlüssel. Bei Überschreitung antwortet die API mit 429.
• Nur lesen: Schreiboperationen sind nicht vorgesehen.

Fragen oder Wünsche zur API? Wenden Sie sich an das Marken-Team.