festia.de API Dokumentation

🚀 Einführung

Mit der festia.de Event-API können Sie als Veranstalter, Agentur oder Ticketing-Dienstleister Ihre Events vollautomatisch zu festia.de übertragen. Jedes übertragene Event wird in eine Warteschlange gelegt, von unserer KI automatisch kategorisiert und zur Veröffentlichung vorbereitet.

✨ Smarte Automatisierung inklusive
Übergeben Sie einfach Ihre Basis-Daten (wie Titel, Datum, Ort und Beschreibung) über unsere JSON-Schnittstelle. Unsere festia KI kümmert sich im Anschluss automatisch um die Vergabe passender Kategorien, die intelligente Verschlagwortung und bereitet die Daten optimal für unsere Plattform auf. Nach erfolgreicher Systemprüfung wird Ihr Event in der Regel vollautomatisch freigegeben.

🛡️ Authentifizierung & Veranstalterprofil
Jeder API-Aufruf muss authentifiziert werden. Senden Sie dazu Ihren API-Schlüssel im Header X-API-KEY mit.

WICHTIG: Jeder API-Schlüssel MUSS zwingend mit einem bestehenden Veranstalterprofil verknüpft sein! Das System überträgt automatisch die rechtlichen Stammdaten (Name, Adresse, Impressum) Ihres Profils auf alle importierten Events. Wenn das verknüpfte Profil gelöscht wird, oder Ihr Account gesperrt ist, wird der Import sofort blockiert (HTTP 403 Forbidden).

⏱️ API Limits (Rate Limiting)
Um die Stabilität der Plattform zu gewährleisten, ist die API auf maximal 250 Importe / Updates pro Tag pro Account limitiert. Wird dieses Limit überschritten, antwortet die API mit einem HTTP 429 Fehler (Too Many Requests).

💡 Kein Programmierer? Kein Problem!

Sie müssen kein IT-Experte sein, um diese Schnittstelle zu nutzen. Eine "API" ist im Grunde nur ein digitaler Briefkasten, in den Sie Daten einwerfen können.

Mit gängigen Automatisierungs-Plattformen können Sie sich die Datenübertragung ganz einfach zusammenklicken, völlig ohne Programmierkenntnisse!

Beispiel 1: "Immer wenn ich ein neues Event in meiner Tabellenkalkulation eintrage, sende es automatisch an festia.de."
Beispiel 2: "Immer wenn in meinem digitalen Kalender ein Termin mit dem Wort 'Event' erstellt wird, sende ihn an festia.de."
Beispiel 3: "Immer wenn ich in meinem eigenen Ticket-System ein Ticket anlege, kopiere die Daten zu festia.de."

Alles was Sie dafür in einer solchen Plattform tun müssen, ist einen "HTTP Request" (Web Request) einzurichten, unseren Link (siehe unten) als Ziel einzugeben und Ihren API-Schlüssel einzufügen.

💸 Kostenlos starten: Zahlreiche Anbieter am Markt bieten kostenfreie Einsteiger-Tarife an. Für kleine bis mittlere Veranstalter reicht das oft völlig aus, um alle Events vollautomatisch und kostenlos zu übertragen!

📤 Event Importieren

Erstellt ein neues Event in Ihrem Account. Das Event erhält initial den Status "Zur Prüfung".

POST https://eventapi.festia.de/v1/events/import.php

Header

Content-Type: application/json
X-API-KEY: fst_live_ihr_api_schluessel_hier

Payload (JSON)

Sie können eine flache JSON-Struktur oder eine logisch verschachtelte Struktur (z.B. location: {...}) nutzen.

Notfall-Updates & Absagen (Echtzeit!)

Müssen Sie ein Event kurzfristig absagen oder verschieben? Nutzen Sie das Feld notice (bzw. alert). Wenn Sie ein bereits importiertes Event per API aktualisieren, wird dieser Text als großer Warn-Banner sofort und in Echtzeit ganz oben auf der Event-Seite bei Festia eingeblendet.

Tipp: Das System fügt das Wort "Absage" nicht automatisch hinzu. Wenn es sich um eine Absage handelt, empfehlen wir den Text mit einem klaren Präfix zu beginnen, z.B.: "🔴 ABGESAGT: Leider fällt das Event heute aus..."

Feld	Typ	Beschreibung
`external_id` oder `identifier` EMPFOHLEN	String	Eindeutige ID aus Ihrem System. Verhindert Duplikate! Wenn Sie ein Event mit einer bereits vorhandenen `external_id` erneut senden, wird das bestehende Event automatisch aktualisiert.
`title` oder `name` PFLICHT	String	Name des Events.
`start_datetime` oder `startDate` PFLICHT	DateTime	Startzeitpunkt (ISO 8601 Format: `YYYY-MM-DDTHH:MM:SS`).
`end_datetime` oder `endDate` PFLICHT	DateTime	Endzeitpunkt (ISO 8601 Format: `YYYY-MM-DDTHH:MM:SS`).
`description` PFLICHT	String	Ausführliche Beschreibung des Events. (URLs werden automatisch gefiltert).
`notice` oder `alert` WICHTIG	String	🚀 ECHTZEIT-BANNER: Wichtige Notfallinfos (z.B. `"ABGESAGT: Unwetterwarnung"`). Wird bei Updates sofort und in Echtzeit als auffälliger Warn-Banner oben auf der Event-Seite geschaltet. Senden Sie einen leeren String `""`, um den Banner wieder zu entfernen.
`intro` oder `abstract`	String	Kurzer Einleitungstext (Teaser).
📍 Standort (Location)
`zip` oder `postal_code` oder `location.address.postalCode` PFLICHT	String	Postleitzahl des Veranstaltungsortes.
`city` oder `addressLocality` oder `location.address.addressLocality` PFLICHT	String	Ort / Stadt.
`address` oder `streetAddress` oder `location.address.streetAddress` PFLICHT	String	Straße und Hausnummer.
`location.address_addon` oder `adresszusatz`	String	Optionaler Adresszusatz (z.B. "Halle 3").
`latitude` / `longitude` oder `location.geo.latitude`	Float	Geodaten (Optional). Wenn nicht übergeben, ermitteln wir diese automatisch im Hintergrund.
👤 Veranstalter (Organizer)
Hinweis zu Veranstalterdaten: Aus rechtlichen Gründen (Impressumspflicht) werden für alle Events immer die Veranstalterdaten aus dem in deinem Account hinterlegten API-Profil genutzt. Die folgenden übergebenen Felder werden im System gespeichert, überschreiben jedoch nicht das Event-Impressum.
`organizer_name`	String	Name des Veranstalters (optional, überschreibt nicht das Profil).
`organizer_email` / `organizer_phone`	String	Kontaktdaten (optional, überschreibt nicht das Profil).
📋 Weitere optionale Felder
`cost` oder `offers.price`	String	Freitext-Feld für Kosten (z.B. "15,00 €" oder "Eintritt frei").
`is_free` oder `kostenfrei` oder `isAccessibleForFree`	Int (0/1)	Explizites Flag (Checkbox), ob das Event komplett kostenlos ist.
`image_url` oder `image`	String	Öffentliche URL zu einem hochauflösenden Titelbild.
`format_indoor`, `format_outdoor`	Int (0/1)	Art der Veranstaltung (`1` = Ja).
`wheelchair_accessible`	Int (0/1)	Barrierefreiheit (Rollstuhlgerecht).
`baby_friendly`	Int (0/1)	Babyfreundlich (z.B. Wickeltisch vorhanden).
`opening_hours` oder `doorTime`	String	Freitext für Öffnungszeiten.
`notes` oder `hinweise`	String	Standard-Hinweise zum Event (z.B. "Keine Glasflaschen", "Einlass ab 18 Jahren"). Diese Informationen werden seitlich bei den Basis-Fakten angezeigt.
`homepage_link` oder `url`	String	Externe Links zur Event-Webseite (auch verschachtelt in `links.website` möglich).
`ticket_link`, `facebook_link`, `instagram_link`, `tiktok_link`	String	Weitere Links zum Event (auch z.B. unter `links: { tickets: "", facebook: "", instagram: "", tiktok: "" }` möglich).

Beispiel Request (cURL)

curl -X POST https://eventapi.festia.de/v1/events/import.php \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: fst_live_1234567890abcdef" \
  -d '{
    "title": "Sommerfest im Park 2026",
    "start_datetime": "2026-07-20T14:00:00",
    "end_datetime": "2026-07-20T23:00:00",
    "zip": "10115",
    "city": "Berlin",
    "address": "Musterpark 1",
    "description": "Das große Sommerfest mit Live-Musik. Kommt vorbei!",
    "cost": "Eintritt frei",
    "organizer_name": "Event Agentur Berlin",
    "image_url": "https://example.com/images/sommerfest.jpg"
  }'

Beispiel-Payloads (JSON)

Die API ist sehr flexibel und versteht verschiedene Formate. Wählen Sie einfach das Format, das am besten zu Ihrem exportierenden System passt.

1. Minimales Format (Flach & Einfach)

Nur die absoluten Pflichtfelder. Perfekt für den schnellen Start mit Zapier, Make oder eigenen simplen Skripten.

{
    "title": "Sommerfest 2026",
    "start_datetime": "2026-07-15T18:00:00",
    "end_datetime": "2026-07-15T23:00:00",
    "zip": "10115",
    "city": "Berlin",
    "address": "Hauptstraße 1",
    "description": "Ein tolles Fest mit Musik und Essen."
}

2. Maximales Format (Alle Optionen & Verschachtelt)

Zeigt alle optionalen Felder und wie sie sauber im JSON-Objekt strukturiert übergeben werden können.

{
    "title": "Großes Sommerfest 2026",
    "intro": "Das Highlight des Jahres für die ganze Familie.",
    "description": "Ein tolles Fest mit Live-Musik, Food-Trucks und einem bunten Kinderprogramm...",
    "start_datetime": "2026-07-15T18:00:00",
    "end_datetime": "2026-07-15T23:00:00",
    "opening_hours": "Einlass ab 17:00 Uhr, Live-Musik ab 19:00 Uhr",
    "location": {
        "zip": "10115",
        "city": "Berlin",
        "address": "Hauptstraße 1",
        "address_addon": "Festwiese hinter Halle 3",
        "latitude": 52.5200,
        "longitude": 13.4050
    },
    "cost": "Eintritt frei",
    "is_free": 1,
    "format_outdoor": 1,
    "baby_friendly": 1,
    "wheelchair_accessible": 1,
    "image_url": "https://mein-server.de/bilder/sommerfest.jpg",
    "links": {
        "website": "https://mein-event.de",
        "tickets": "https://tickets.de/123",
        "instagram": "https://instagram.com/event",
        "tiktok": "https://tiktok.com/@event"
    },
    "organizer": {
        "name": "Kulturverein Berlin e.V.",
        "email": "kontakt@kulturverein.de",
        "phone": "+49 30 123456"
    }
}

3. Schema.org / JSON-LD (Kompatibilitäts-Alias)

Nutzt Ihr System Standard-Begriffe nach Schema.org? Unsere API fängt diese automatisch als Alias ab (inklusive voller Unterstützung aller Felder).

{
    "@context": "https://schema.org",
    "@type": "Event",
    "name": "Großes Sommerfest 2026",
    "abstract": "Das Highlight des Jahres für die ganze Familie.",
    "description": "Ein tolles Fest mit Live-Musik, Food-Trucks und einem bunten Kinderprogramm...",
    "startDate": "2026-07-15T18:00:00",
    "endDate": "2026-07-15T23:00:00",
    "doorTime": "Einlass ab 17:00 Uhr",
    "isAccessibleForFree": true,
    "url": "https://mein-event.de",
    "image": "https://mein-server.de/bilder/sommerfest.jpg",
    "location": {
        "@type": "Place",
        "address": {
            "@type": "PostalAddress",
            "postalCode": "10115",
            "addressLocality": "Berlin",
            "streetAddress": "Hauptstraße 1"
        },
        "geo": {
            "@type": "GeoCoordinates",
            "latitude": 52.5200,
            "longitude": 13.4050
        }
    },
    "offers": {
        "@type": "Offer",
        "price": "Eintritt frei",
        "url": "https://tickets.de/123"
    },
    "organizer": {
        "@type": "Organization",
        "legalName": "Kulturverein Berlin e.V.",
        "email": "kontakt@kulturverein.de",
        "telephone": "+49 30 123456"
    }
}

Antwort (Erfolg)

HTTP/1.1 201 Created
{
  "status": "success",
  "message": "Event imported successfully.",
  "event_id": 1042
}

Antwort (Fehler & Limits)

Falls ein Fehler auftritt, liefert die API einen entsprechenden HTTP-Statuscode und eine aussagekräftige JSON-Nachricht zurück.

HTTP 401: Unauthorized

Der API-Key fehlt im Header oder ist ungültig.

HTTP 403: Forbidden

Der Account wurde vom Administrator gesperrt oder es existiert kein Veranstalterprofil für diesen API-Key.

HTTP 429: Too Many Requests

Das Tageslimit von 250 API-Anfragen pro Account wurde für heute erreicht.

HTTP 400: Bad Request

Ein Pflichtfeld fehlt oder die übergebenen Daten (z.B. Datumsformat) sind ungültig.

🧪 API Test-Modus

Um Ihre Integration gefahrlos zu testen, können Sie Payloads an unseren Test-Endpunkt senden. Diese Daten werden nicht live geschaltet, sondern nur in Ihrem Dashboard als "Gültig" oder "Fehlerhaft" inklusive einer Fehleranalyse angezeigt.

POST https://eventapi.festia.de/v1/events/test_import.php

Senden Sie genau denselben Payload wie für die Live-API. Loggen Sie sich anschließend in Ihren festia.de Account ein und öffnen Sie Meine Events → Entwickler / API. Dort sehen Sie das Ergebnis im API Test-Monitor.

🚀 Interaktives Test-Tool öffnen

Testen Sie Ihren API-Key und Payload direkt im Browser.

Event-API Dokumentation