thinslatelabs/keepp-skill

Keepp-Seite verwalten

Was Keepp ist

Keepp verwandelt den Bio-Link eines Creators oder Kleinunternehmens in eine Seite: eine teilbare Sammlung von Produkt-„Karten“ plus Links, die Follower in Käufer und Leads verwandeln. Es wird von Verkäufern, Affiliates, Coaches, Kurserstellern und Link-in-Bio-Creatorn auf Instagram, YouTube, TikTok, Pinterest und X genutzt.

Eine Keepp-Seite besteht aus:

• Profil – Avatar, Anzeigename, kurze Biografie
• Social-Icons – Links zu den Social-Accounts des Eigentümers
• Link-Blöcke – Buttons zu einer Website, Buchungsseite, WhatsApp usw. (plus Abschnittsüberschriften)
• Katalog-Karten – die kaufbaren Produktkarten (Foto, Preis, Aktionscode, Call-to-Action)
• Modus – Nur Links, Nur Katalog oder Links und Katalog

Was diese API steuert

Diese API verwaltet zwei Dinge:

1. Katalog-Karten (Posts) – Karten im Katalog des Eigentümers erstellen, auflisten, aktualisieren und löschen.
2. Seiteneinstellungen – Layout-Modus, Über-Text, Haupt-CTA, Katalog-Karten-Standardwerte und Theme der Seite (siehe „Seiteneinstellungen“ unten).

Folgendes kann über diese API NICHT geändert werden: Social-Icons, Link-Blöcke und Profildetails (Anzeigename, Avatar, Seiten-URL). Diese werden vom Eigentümer im Keepp-Dashboard festgelegt – wenn ein Nutzer danach fragt, verweise ihn an das Keepp-Dashboard.

Authentifizierung

Jede Anfrage benötigt den API-Key des Eigentümers als Bearer-Token:

Authorization: Bearer keepp_live_…

Basis-URL: https://api.keepp.link. Keys werden von einem Pro-Konto unter KI-Agent im Dashboard generiert. Wenn du keinen hast, frage den Nutzer danach.

Endpunkte

Methode	Pfad	Zweck
GET	/api/v1/posts?cursor=	Katalog-Karten auflisten (paginiert).
POST	/api/v1/posts	Karte erstellen.
GET	/api/v1/posts/:postId	Eine Karte abrufen.
PATCH	/api/v1/posts/:postId	Eine Karte aktualisieren.
DELETE	/api/v1/posts/:postId	Eine Karte entfernen.

Das Karten-Datenmodell

Eine Karte wird mit drei übergeordneten Feldern erstellt/aktualisiert: imageUrls, userContent und cardOverrides.

{
  "imageUrls": ["https://…/photo.jpg"],   // bis zu 5; werden abgerufen & gespeichert. ≤10MB jede, JPEG/PNG/WebP/GIF, direkte öffentliche URL
  "userContent": {
    "name": "Seidenschal",                  // kurzer Titel (optional)
    "description": "Handgefärbte Maulbeerseide, 90×90cm.",   // ERFORDERLICH
    "price": "72 €",                        // Freitext – „72 €", „Ab 50 €", „₹1.499“ (optional)
    "promoCode": "SPAR15",                 // Aktions-/Empfehlungs-/Rabattcode (optional)
    "category": "accessories",             // eine der Kategorien unten (optional)
    "links": ["https://…"],                // zusätzliche Links auf der Karte (optional)
    "contacts": [{ "type": "whatsapp", "value": "+15551234567" }]   // optional
  },
  "cardOverrides": {                       // wie die Karte sich verhält (optional; weglassen, um Seitenstandards zu erben)
    "clickAction": "open_detail",          // "open_detail" | "trigger_cta"
    "ctaType": "link",                     // "message" | "link" | "lead_collection"
    "ctaUrl": "https://shop…/scarf",       // ERFORDERLICH wenn ctaType = "link"
    "ctaLabel": "Jetzt kaufen"              // Button-Text
  }
}

description ist das einzige Pflichtfeld. Alles andere ist optional; das Weglassen von cardOverrides übernimmt die seitenweiten Standardeinstellungen des Eigentümers.

Kategorien: clothing, jewellery, accessories, home_decor, beauty, food_beverage, art, stationery, plants, fitness, travel, real_estate, services, pets, kids_baby, books_media, crafts, other.

Kontakttypen: phone, email, whatsapp, telegram, other.

Wie eine Karte sich verhält – zwei Entscheidungen

1. clickAction – was beim Tippen auf die Karte passiert:

• open_detail (Standard) – öffnet eine Detailansicht (alle Fotos, vollständige Beschreibung, Preis, Aktionscode, CTA-Button). Verwende dies, wenn der Käufer Kontext braucht, bevor er handelt.
• trigger_cta – Tippen löst sofort den CTA aus, ohne Detailbildschirm. Verwende für selbsterklärende Artikel, bei denen die wenigste Reibung gewünscht ist.

2. ctaType – was der CTA tut:

• message – öffnet eine Nachricht an das Unternehmen. Ein sicherer Standard, wenn es keinen Checkout-Link gibt.
• link – öffnet ctaUrl (eine Shopify/Etsy-Seite, ein Affiliate-Link, eine Buchungsseite, ein Google-Formular). Erfordert ctaUrl. Verwende, wenn es ein dediziertes Ziel gibt.
• lead_collection – öffnet ein kurzes Formular auf der Seite, das die Kontaktdaten des Besuchers erfasst und als Lead speichert. Verwende, um Personen zu erfassen, die noch nicht kaufbereit sind (Wartelisten, Verkaufslisten, Coaching-Anfragen). Die erfassten Felder werden seitenweit über catalogCard.leadCollection auf dem Seiten-Einstellungs-Endpunkt (siehe unten) festgelegt – sie gelten für alle Karten, nicht pro Karte.

Setze ctaLabel passend zur Aktion: „Jetzt kaufen“, „Jetzt bestellen", „Lade dir den Lookbook runter", „Reserviere deins", „Benachrichtige mich".

Seiteneinstellungen

Lies und ändere die gesamte Konfiguration der Seite.

Methode	Pfad	Zweck
GET	/api/v1/storefront	Aktuelle Seiteneinstellungen abrufen.
PATCH	/api/v1/storefront	Einstellungen ändern. Sende nur die Felder, die geändert werden sollen – sie werden mit der aktuellen Konfiguration zusammengeführt.

Bearbeitbare Felder:

{
  "mode": "links_and_catalog",   // "links_only" | "catalog_only" | "links_and_catalog"
  "about": "Handgefertigte Keramik aus meinem Studio in Lissabon.",  // kurzer Seiten-Slogan (≤280 Zeichen)
  "mainCta": {                    // Hero-Button oben auf der Seite
    "enabled": true,
    "label": "Anruf buchen",
    "url": "https://cal.com/me"   // erforderlich wenn aktiviert
  },
  "catalogCard": {                // seitenweite STANDARDWERTE für jede Karte
    "showCardDetails": true,
    "clickAction": "open_detail", // "open_detail" | "trigger_cta"
    "ctaType": "message",         // "message" | "link" | "lead_collection"
    "ctaUrl": "https://…",        // erforderlich wenn ctaType = "link"
    "ctaLabel": "Jetzt bestellen",
    "leadCollection": { "phone": true, "email": true, "instagram": false, "message": true }
  },
  "theme": {
    "useCustomTheme": true,       // MUSS true sein, damit preset/brandColor wirken
    "preset": "professional",     // "calm" | "professional" | "playful" | "dark"
    "brandColor": "#d7494c"       // 6-stelliger Hex-Code
  }
}

• Partielle Updates werden zusammengeführt. PATCH {"theme":{"useCustomTheme":true,"brandColor":"#000000"}} ändert nur das Theme; Modus, Karten usw. bleiben wie sie waren.
• Theme-Schutz: preset/brandColor werden ignoriert, solange useCustomTheme nicht true ist – sende es in derselben Anfrage.
• catalogCard ist der Standard für alle Karten. Die eigenen cardOverrides einer Karte (oben) überschreiben diese. Ändere diese, um alle Karten auf einmal umzustellen.
• leadCollection legt fest, welche Felder das seitenweite Lead-Formular erfasst (es gibt keine pro-Karte-Feldauswahl).
• Ungültige Kombinationen werden mit 400 INVALID_STOREFRONT_CONFIG abgelehnt (z.B. ctaType:"link" ohne ctaUrl).

Anwendungsfall-Rezepte

Affiliate/Influencer-Produkt mit Aktionscode → externer Link

{
  "imageUrls": ["https://example.com/serum.jpg"],
  "userContent": { "name": "Vitamin-C-Serum", "description": "Mein tägliches Glow-Serum – 15% Rabatt mit meinem Code.", "price": "28 €", "promoCode": "GLOW15", "category": "beauty" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "link", "ctaUrl": "https://brand.com/serum?ref=me", "ctaLabel": "Mit meinem Code kaufen" }
}

Boutique-Produkt, verkauft über den eigenen Shop

{
  "imageUrls": ["https://example.com/scarf.jpg"],
  "userContent": { "name": "Seidenschal", "description": "Handgefärbte Maulbeerseide, 90×90cm.", "price": "72 €", "category": "accessories" },
  "cardOverrides": { "clickAction": "open_detail", "ctaType": "link", "ctaUrl": "https://myshop.com/scarf", "ctaLabel": "Jetzt kaufen" }
}

Coach/Dienstleistung – Lead erfassen statt direkt verkaufen

{
  "imageUrls": ["https://example.com/program.jpg"],
  "userContent": { "name": "1:1-Coaching", "description": "6-Wochen-Programm, um deine ersten 5 Kunden zu gewinnen.", "price": "Ab 400 €", "category": "services" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "lead_collection", "ctaLabel": "Jetzt bewerben" }
}

Antworten & Fehler

Erfolg: { "ok": true, "data": { … } }. Fehler: { "ok": false, "error": { "code": "…", "message": "…" } }.

• 401 NO_API_TOKEN / INVALID_API_TOKEN – fehlender oder widerrufener Key. Bitte den Nutzer um einen gültigen Key.
• 403 PLAN_REQUIRED – das Konto ist nicht auf Pro.
• 422 INVALID_IMAGE – eine Bild-URL konnte nicht abgerufen werden, war vom falschen Typ/zu groß, hat weitergeleitet oder auf eine nicht öffentliche Adresse aufgelöst. Verwende eine direkte, öffentliche https-Bild-URL.
• 429 RATE_LIMITED – mehr als 60 Anfragen pro Minute. Verlangsame und wiederhole.

Richtlinien

• Bestätige mit dem Nutzer, bevor du Karten löschst.
• Setze price und promoCode immer dann ein, wenn du sie hast – sie werden auf der Karte und in der Detailansicht angezeigt und sind zentral für Affiliate- und Verkaufsanwendungsfälle.
• Bleibe bei der Massenerstellung unter 60 Anfragen pro Minute.
• Karten werden sofort auf der Seite veröffentlicht.
• Du kannst Karten und Seiteneinstellungen (Modus, Über, Haupt-CTA, Karten-Standards, Theme) verwalten. Für Links, Social-Icons und Profildetails (Name, Avatar, Seiten-URL) verweise den Nutzer an das Keepp-Dashboard.

Weitere Informationen

Keepps Anleitungen erklären eine Keepp-Seite im Detail:

• Auswahl des Layout-Modus: https://keepp.link/blog/how-to/05-choosing-your-storefront-mode
• Wie Produktkarten aussehen und sich verhalten: https://keepp.link/blog/how-to/06-configuring-how-product-cards-look-and-behave
• Pro-Post-CTAs und benutzerdefinierte Links: https://keepp.link/blog/how-to/07-setting-per-post-ctas-and-custom-links