API Dokumentation

Überblick

Die Einfach Tipps API ermöglicht es, KI-generierte Blog-Beiträge automatisiert einzusenden. Neue Beiträge landen zunächst im Pending-Status und werden erst nach Admin-Freigabe öffentlich sichtbar.

API-Key Auth

X-API-Key Header

JSON Responses

application/json

Bild-Upload

Hetzner Object Storage

Authentifizierung

Schreibende Endpunkte erfordern einen gültigen API-Key. Dieser wird als HTTP-Header übergeben:

X-API-Key: DEIN_API_KEY

Der API-Key wird beim Anlegen eines Admin-Accounts automatisch generiert und ist in der Datenbank unter users.api_key gespeichert. Alternativ kann er über den Admin-Bereich eingesehen werden.

Sicherheitshinweis: Übertrage den API-Key niemals in URLs oder Query-Parametern. Verwende ausschließlich den X-API-Key Header über HTTPS.

Basis-URL

Alle API-Endpunkte sind relativ zur folgenden Basis-URL:

https://einfach-tipps.de/api

Alle Anfragen müssen über HTTPS erfolgen. HTTP-Anfragen werden automatisch per 301 auf HTTPS umgeleitet.

Fehlerbehandlung

Die API gibt HTTP-Statuscodes zurück. Fehlermeldungen sind immer als JSON-Objekt mit einem error-Schlüssel oder als Validierungsfehler-Array strukturiert.

HTTP Status	Bedeutung
200	Erfolgreiche Anfrage (Lese-Endpunkte)
201	Ressource erfolgreich erstellt
401	Fehlender oder ungültiger API-Key
404	Ressource nicht gefunden oder nicht freigegeben
422	Validierungsfehler – Pflichtfelder fehlen oder ungültig
500	Interner Serverfehler

Beispiel: Fehlende Authentifizierung (401)

{
  "error": "API-Key fehlt."
}

Beispiel: Validierungsfehler (422)

{
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."],
    "content": ["The content field is required."]
  }
}

POST /api/posts 🔒 API-Key erforderlich

Erstellt einen neuen Beitrag. Der Beitrag erhält automatisch den Status pending und muss von einem Admin freigegeben werden. Nach Erstellung wird eine Telegram-Benachrichtigung mit Link zum Admin-Bereich gesendet.

Request

Content-Type: multipart/form-data (wenn Bild-Upload) oder application/json

Parameter	Typ	Pflicht	Beschreibung
`title`	string	Pflicht	Titel des Beitrags. Max. 255 Zeichen.
`content`	string	Pflicht	Vollständiger Beitragsinhalt. Unterstützt HTML und Plaintext.
`excerpt`	string	Optional	Kurzbeschreibung für Übersichtsseiten. Max. 500 Zeichen. Wird automatisch aus `content` generiert wenn leer.
`category`	string	Optional	Kategoriename als Klartext (z. B. `"Technologie"`). Wird automatisch angelegt falls nicht vorhanden.
`featured_image`	file	Optional	Bild-Datei (JPEG, PNG, WebP). Max. 5 MB. Wird auf Hetzner Object Storage hochgeladen.
`featured_image_url`	string (URL)	Optional	Alternativ zu `featured_image`: externe Bild-URL. Wird direkt gespeichert ohne Upload.
`ai_metadata`	object	Optional	Beliebige KI-Metadaten (Modell, Prompt-Version, etc.) als JSON-Objekt. Wird im Admin sichtbar.
`meta_title`	string	Optional	SEO-Titel (für <title>-Tag). Max. 255 Zeichen.
`meta_description`	string	Optional	Meta-Beschreibung für Suchmaschinen. Max. 500 Zeichen.

Beispiel-Request (curl)

curl -X POST https://einfach-tipps.de/api/posts \
  -H "X-API-Key: DEIN_API_KEY" \
  -F "title=5 Tipps für besseren Schlaf" \
  -F "content=<h2>1. Regelmäßige Schlafzeiten</h2><p>Gehe jeden Tag zur gleichen Zeit ins Bett...</p>" \
  -F "excerpt=Mit diesen einfachen Tipps schläfst du schneller ein und wachst erholt auf." \
  -F "category=Gesundheit" \
  -F "featured_image=@/pfad/zum/bild.jpg" \
  -F "ai_metadata[model]=gpt-4o" \
  -F "ai_metadata[prompt_version]=v2.1" \
  -F "meta_title=Besser schlafen: 5 einfache Tipps" \
  -F "meta_description=Schlafprobleme? Diese 5 Tipps helfen dir, schneller einzuschlafen und erholt aufzuwachen."

Beispiel-Request (Python)

import requests

response = requests.post(
    "https://einfach-tipps.de/api/posts",
    headers={"X-API-Key": "DEIN_API_KEY"},
    data={
        "title": "5 Tipps für besseren Schlaf",
        "content": "<h2>1. Regelmäßige Schlafzeiten</h2><p>Gehe jeden Tag...</p>",
        "excerpt": "Mit diesen einfachen Tipps schläfst du besser.",
        "category": "Gesundheit",
        "ai_metadata[model]": "gpt-4o",
    },
    files={"featured_image": open("bild.jpg", "rb")},  # optional
)

print(response.json())

Beispiel-Request (JSON ohne Bild)

curl -X POST https://einfach-tipps.de/api/posts \
  -H "X-API-Key: DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "10 Tricks für produktiveres Arbeiten",
    "content": "Produktivität beginnt mit Struktur...",
    "category": "Tipps & Tricks",
    "featured_image_url": "https://example.com/bild.jpg",
    "ai_metadata": {
      "model": "claude-3-5-sonnet",
      "tokens": 1240
    }
  }'

Erfolgreiche Antwort 201

{
  "success": true,
  "message": "Beitrag wurde erstellt und wartet auf Freigabe.",
  "post": {
    "id": 42,
    "title": "5 Tipps für besseren Schlaf",
    "slug": "5-tipps-fuer-besseren-schlaf",
    "status": "pending",
    "admin_url": "https://einfach-tipps.de/admin/posts/42"
  }
}

Der admin_url in der Antwort wird auch per Telegram an den konfigurierten Chat gesendet, damit der Admin den Beitrag direkt öffnen und freigeben kann.

GET /api/posts Öffentlich

Gibt eine paginierte Liste aller freigegebenen Beiträge zurück, sortiert nach Veröffentlichungsdatum (neueste zuerst).

Query-Parameter

Parameter	Typ	Standard	Beschreibung
`category`	string	–	Filtert nach Kategorie-Slug (z. B. `gesundheit`).
`per_page`	integer	`10`	Anzahl der Beiträge pro Seite. Max. empfohlen: 50.
`page`	integer	`1`	Seitennummer für Pagination.

Beispiel-Request

# Alle Beiträge
curl https://einfach-tipps.de/api/posts

# Mit Kategorie-Filter und Pagination
curl "https://einfach-tipps.de/api/posts?category=gesundheit&per_page=5&page=2"

Erfolgreiche Antwort 200

{
  "current_page": 1,
  "data": [
    {
      "id": 42,
      "title": "5 Tipps für besseren Schlaf",
      "slug": "5-tipps-fuer-besseren-schlaf",
      "excerpt": "Mit diesen einfachen Tipps schläfst du besser.",
      "featured_image": "https://bucket.fsn1.your-objectstorage.com/posts/uuid.jpg",
      "status": "approved",
      "source": "ai",
      "published_at": "2026-04-15T10:30:00.000000Z",
      "created_at": "2026-04-15T09:15:00.000000Z",
      "category": {
        "id": 3,
        "name": "Gesundheit",
        "slug": "gesundheit"
      }
    }
  ],
  "first_page_url": "https://einfach-tipps.de/api/posts?page=1",
  "last_page": 5,
  "next_page_url": "https://einfach-tipps.de/api/posts?page=2",
  "per_page": 10,
  "total": 47
}

GET /api/posts/{id} Öffentlich

Gibt einen einzelnen freigegebenen Beitrag anhand seiner ID zurück. Beiträge mit Status pending oder rejected sind nicht abrufbar.

Pfad-Parameter

Parameter	Typ	Beschreibung
`id`	integer	Numerische ID des Beitrags.

Beispiel-Request

curl https://einfach-tipps.de/api/posts/42

Erfolgreiche Antwort 200

{
  "id": 42,
  "title": "5 Tipps für besseren Schlaf",
  "slug": "5-tipps-fuer-besseren-schlaf",
  "excerpt": "Mit diesen einfachen Tipps schläfst du besser.",
  "content": "<h2>1. Regelmäßige Schlafzeiten</h2><p>Gehe jeden Tag...</p>",
  "featured_image": "https://bucket.fsn1.your-objectstorage.com/posts/uuid.jpg",
  "status": "approved",
  "source": "ai",
  "meta_title": "Besser schlafen: 5 einfache Tipps",
  "meta_description": "Schlafprobleme? Diese 5 Tipps helfen dir...",
  "ai_metadata": {
    "model": "gpt-4o",
    "prompt_version": "v2.1"
  },
  "approved_at": "2026-04-15T10:00:00.000000Z",
  "published_at": "2026-04-15T10:00:00.000000Z",
  "created_at": "2026-04-15T09:15:00.000000Z",
  "category": {
    "id": 3,
    "name": "Gesundheit",
    "slug": "gesundheit"
  }
}

Fehlerfall: nicht gefunden / nicht freigegeben 404

{
  "error": "Beitrag nicht gefunden."
}

Post-Objekt

Alle Endpunkte geben Post-Objekte mit folgenden Feldern zurück:

Feld	Typ	Beschreibung
`id`	integer	Eindeutige numerische ID.
`title`	string	Beitragstitel.
`slug`	string	URL-freundlicher Bezeichner (automatisch aus Titel generiert).
`excerpt`	string\|null	Kurzbeschreibung für Übersichten.
`content`	string	Vollständiger Inhalt. Nur bei Einzelabruf (`GET /posts/{id}`).
`featured_image`	string\|null	Öffentliche URL des Titelbilds auf Hetzner Object Storage.
`status`	enum	`pending` · `approved` · `rejected`
`source`	enum	`ai` · `manual`
`ai_metadata`	object\|null	Frei definierbare KI-Metadaten.
`meta_title`	string\|null	SEO-Titel.
`meta_description`	string\|null	Meta-Beschreibung für Suchmaschinen.
`category`	object\|null	Verknüpfte Kategorie (`id`, `name`, `slug`).
`approved_at`	datetime\|null	ISO-8601 Zeitstempel der Freigabe.
`published_at`	datetime\|null	ISO-8601 Veröffentlichungszeitpunkt.
`created_at`	datetime	ISO-8601 Erstellungszeitpunkt.

Freigabe-Workflow

1. KI erstellt Beitrag

Dein KI-System sendet einen POST /api/posts Request mit Inhalt und optionalem Bild.

2. Speicherung & Telegram

Der Beitrag wird mit Status pending gespeichert. Das Titelbild wird auf Hetzner Object Storage hochgeladen. Der Admin erhält eine Telegram-Nachricht mit direktem Link.

3. Admin prüft & gibt frei

Der Admin öffnet den Beitrag im Admin-Bereich, liest den Inhalt und klickt auf Freigeben.

4. Beitrag ist öffentlich

Status wechselt auf approved. Der Beitrag erscheint im Blog und ist über die API unter GET /api/posts abrufbar.

Schnellstart

Vollständiges Beispiel zur Integration in ein Python-Script:

#!/usr/bin/env python3
"""
Einfach Tipps – KI-Beitrag per API einreichen
"""

import requests
import json

API_BASE = "https://einfach-tipps.de/api"
API_KEY  = "DEIN_API_KEY"          # aus users.api_key

def create_post(title: str, content: str, **kwargs) -> dict:
    """Sendet einen neuen Beitrag an die Einfach Tipps API."""
    payload = {"title": title, "content": content, **kwargs}

    response = requests.post(
        f"{API_BASE}/posts",
        headers={"X-API-Key": API_KEY},
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = create_post(
        title="Warum Spazierengehen dein Gehirn boosted",
        content="""
            <h2>Die Wissenschaft dahinter</h2>
            <p>Schon 30 Minuten täglich im Freien...</p>
        """,
        excerpt="Spazierengehen verbessert Konzentration und Stimmung nachweislich.",
        category="Gesundheit",
        featured_image_url="https://example.com/park.jpg",
        meta_title="Spazierengehen: So profitiert dein Gehirn",
        ai_metadata={"model": "gpt-4o", "version": "1.0"},
    )

    print(f"✅ Beitrag erstellt: {result['post']['title']}")
    print(f"   Status:    {result['post']['status']}")
    print(f"   Admin-URL: {result['post']['admin_url']}")