Entwickeln Sie auf Eyivo mit einer strukturierten API.

1. Überblick

Die Eyivo REST API ist die programmatische Steuerschnittstelle für strukturierte Websites. Sie verwendet HTTPS und JSON, ist unter /api/v1 versioniert und wendet dieselben Regeln für Eigentümerschaft, Tarifgrenzen, Validierung und Nachvollziehbarkeit an wie das Dashboard.

Versionierung: Änderungen, die den Schnittstellenvertrag brechen, erfordern eine neue Basisversion. Bestehende JSON-Objekte können zusätzliche Felder erhalten; Clients sollten unbekannte Felder ignorieren.

2. Schnellstart

1. 1
   Token erstellen.

   Melden Sie sich in der App an, öffnen Sie die API-Token, wählen Sie nur die benötigten Berechtigungen und kopieren Sie das ey_ Token, wenn es angezeigt wird.

2. 2
   Eigene Websites auflisten.

   Prüfen Sie die Authentifizierung und ermitteln Sie die numerische Website-ID für untergeordnete Endpunkte.

3. 3
   Idempotente Schreibvorgänge senden.

   Vergeben Sie für jede POST-, PATCH- und DELETE-Anfrage einen eigenen Idempotency-Key.

curl --request GET \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token'

Eine erfolgreiche Antwort auf eine Listenanfrage enthält die Einträge unter data:

{
  "data": [
    {
      "id": 42,
      "platform_subdomain_key": "7kr9mp2x",
      "template_key": "corporate-01",
      "status": "active",
      "native_locale": "en",
      "english_enabled": false,
      "content_version": 1,
      "search_visibility": "platform_noindex"
    }
  ]
}

3. Authentifizierung

Jede Anfrage an /api/v1 benötigt ein Bearer-Token:

Authorization: Bearer <token>

PKCE-Autorisierungsablauf

1. Erzeugen Sie einen zufälligen code_verifier mit hoher Entropie und den zugehörigen SHA-256-code_challenge.
2. Leiten Sie den Nutzer an /oauth/authorize weiter. Übergeben Sie response_type=code, die öffentliche client_id, die exakt registrierte redirect_uri, die durch Leerzeichen getrennten scope-Werte, state, code_challenge und code_challenge_method=S256.
3. Prüfen Sie nach der Weiterleitung state und tauschen Sie den erhaltenen Autorisierungscode bei /oauth/token mit dem ursprünglichen code_verifier ein.
4. Speichern Sie Access- und Refresh-Token sicher. Erneuern Sie sie vor Ablauf und ersetzen Sie rotierte Zugangsdaten atomar.

4. Berechtigungsbereiche

Anfragen benötigen den jeweils unten angegebenen Berechtigungsbereich. Ein persönliches Token mit * besteht alle Berechtigungsprüfungen; Anwendungen sollten trotzdem nur die erforderlichen Bereiche anfordern.

REST benötigt den Endpunkt-Scope, nicht mcp:use. Medienendpunkte nutzen media:read oder media:write.

5. Idempotente Schreibvorgänge

Senden Sie bei JSON-Änderungen einen Idempotency-Key für sichere Wiederholungen. Multipart-Uploads und Upload-Tickets sind ausgenommen; prüfen Sie vor einer Wiederholung das Übertragungsergebnis.

Idempotency-Key: site-42-page-create-01J7M6Y8RRF3ZE6WB4Z0Y9XJXC

Zum Vergleich einer Anfrage gehören HTTP-Methode, Pfad und exakt derselbe Rohdaten-Body. Verwenden Sie bei Wiederholungen das ursprünglich serialisierte JSON.

6. Antworten und Datenstrukturen

Inhaltsoperationen liefern einen data-Umschlag. MCP liefert structuredContent plus eine JSON-Textkopie; REST liefert JSON. Die Ausgabeschemas beschreiben IDs, Veröffentlichungsbereitschaft und Paginierung. Folgen Sie den Seiteninformationen für Blogs, Medien und Einsendungen.

{ "data": { "id": 42, "status": "active" } }

{ "data": [{ "id": 42 }, { "id": 43 }] }

Sammlungsformate unterscheiden sich. Folgen Sie den dokumentierten Paginierungsdaten; nicht jedes Ergebnis ist eine flache oder unpaginierte Liste.

7. Websites

Website erstellen

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: site-create-01J7M6Y8' \
  --data '{
    "display_name": "Northstar Studio",
    "template_key": "corporate-01",
    "native_locale": "en"
  }'

Antwort: 201 Created mit einer Website-Ressource. Während der Bereitstellung kann zunächst ein nicht aktiver Status angezeigt werden. Bei Überschreitung von Website- oder Tarifgrenzen wird 422 zurückgegeben.

Felder der Website-Ressource: id, platform_subdomain_key, template_key, status, native_locale, english_enabled, content_version, search_visibility, optional runtime und Zeitstempel.

8. Seiten

Seite erstellen

{
  "type": "page",
  "sort_order": 300,
  "locale": "en",
  "slug": "our-story",
  "title": "Our story",
  "body": "<p>How the company began.</p>",
  "meta_title": "Our story | Northstar Studio",
  "meta_description": "Learn about Northstar Studio."
}

Antwort bei Erstellung: 201. Antwort bei Aktualisierung: 200. Antwort bei Löschung: 204 ohne Body.

Speichern Sie einen Entwurf, prüfen Sie seine Veröffentlichungsbereitschaft und veröffentlichen Sie das Element in der gewünschten Sprache, wenn der Nutzer es live schalten möchte. Andere Entwürfe bleiben unverändert.

9. Katalogeinträge

Katalogeintrag erstellen

{
  "sort_order": 100,
  "locale": "en",
  "slug": "strategy-advisory",
  "title": "Strategy advisory",
  "summary": "Focused advice for consequential decisions.",
  "body": "Talk to our senior advisory team."
}

Speichern Sie einen Entwurf, prüfen Sie seine Veröffentlichungsbereitschaft und veröffentlichen Sie das Element in der gewünschten Sprache, wenn der Nutzer es live schalten möchte. Andere Entwürfe bleiben unverändert.

Dies sind Beispiele nach Inhaltsbereich. Vollständige Ein-/Ausgabeschemas und Scopes stehen in tools/list oder OpenAPI. Die REST-Pfade sind relativ zu /api/v1/sites/{site}.

Fähigkeiten und Bearbeitungsvertrag

Wählen Sie eine Website und lesen Sie ihre Fähigkeiten: aktivierte Sprachen, Theme-Felder, Komponentenschemas, Menüpositionen und installierte Plugin-Panels. Lesen Sie vor Änderungen die Ressource content-workflow. Ohne Ressourcenunterstützung nutzen Sie get-site-capabilities-tool. Folgen Sie tools/list nextCursor bis zum Ende.

GET /api/v1/sites/{site}/capabilities
GET /api/v1/sites/{site}/pages/{page_id}/components/schema?locale=en

Nutzen Sie die gewünschte Sprache und die aktuelle version oder revision. Blog-Speicherungen ersetzen das ganze Dokument und löschen dessen Zeitplanung. Menüs verwenden eine numerische revision; Inhaltszuweisungen einen separaten menu_revision-Hash. Bewahren Sie Einträge in ersetzten Arrays. Lesen und kombinieren Sie Änderungen bei Konflikten erneut.

Die Hauptnavigation bleibt automatisch. Zusätzliche Menüs haben eigene Entwürfe und Veröffentlichungen. Inhaltsspeicherungen merken Menüzuweisungen vor; die Veröffentlichung dieses Elements übernimmt sie, ohne andere Menüentwürfe zu veröffentlichen. Ein Menü veröffentlicht nie verlinkte Inhalte. source_hash schützt Übersetzungen vor veraltetem Ausgangstext.

Seiteninhalte und richtext-Felder akzeptieren bereinigtes HTML. list-page-links-tool liefert stabile /__eyivo/pages/{id}-Links, die nach Veröffentlichung in der Besuchersprache aufgelöst werden. Blogs verwenden strukturiertes document-JSON mit websiteeigenen media_id und Seiten-/Beitragszielen, kein body_html.

{
  "type": "doc",
  "content": [{
    "type": "paragraph",
    "content": [{ "type": "text", "text": "Our story" }]
  }]
}

Bilder und Videos hochladen

upload-media-tool öffnet eine Dateiauswahl in MCP-Apps-Clients wie Claude. ChatGPT kann seine eigene Anhangreferenz übergeben; ein Claude-Chat-Anhang ist keine OpenAI-Dateireferenz. Erfinden Sie keine Download-URLs und senden Sie keine Base64-Dateien als Tool-Argumente.

Codex und Claude Code können prepare-media-upload-tool aufrufen und die Datei innerhalb von fünf Minuten als Multipart an upload_url mit dem einmaligen upload_token senden. Halten Sie das Token geheim. REST-Clients können ihren eigenen media:write-Bearer verwenden. Erst der abgeschlossene Upload liefert die Medien-ID; ein Ticket allein lädt keine Datei hoch.

POST /api/v1/sites/{site}/media
Authorization: Bearer <media:write token>
Content-Type: multipart/form-data; boundary=<generated by HTTP client>

file: <original file bytes>

10. Eigene Domains

Domain anfordern

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites/42/domains \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: domain-request-example-com' \
  --data '{"domain":"www.example.com"}'

Eine ausstehende Domain-Ressource enthält verification_token. Fügen Sie mit dem für Ihre Domain zurückgegebenen Wert den erforderlichen DNS-Eintrag zum Eigentumsnachweis hinzu. Warten Sie auf die DNS-Weitergabe und rufen Sie dann den Aktivierungsendpunkt auf. Nach der Aktivierung können Sie den Endpunkt für den primären Hostnamen aufrufen, falls die Domain kanonisch werden soll.

Felder der Domain-Ressource: id, domain, site_id, is_primary, status, gegebenenfalls verification_token und Zeitstempel. Bei Tarifgrenzen für eigene Domains oder fehlgeschlagener Domain-Validierung wird 422 zurückgegeben.

11. Fehler

Validierungsantwort

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

Antwort bei fehlgeschlagener Authentifizierung oder Autorisierung

{
  "message": "Missing required scope [content:write]."
}

12. Aktuelle Grenzen und Integrationscheckliste

REST v1 stellt bewusst nur einen Teil von Eyivo bereit. Ein fehlender Endpunkt bedeutet eine Grenze des Schnittstellenvertrags und erlaubt keinen Aufruf interner APIs.

Vor dem produktiven Einsatz

• HTTPS verwenden und den erwarteten Host app.eyivo.com prüfen.
• Bearer-Token serverseitig aufbewahren und Autorisierungsheader aus Protokollen entfernen.
• Nur erforderliche Berechtigungen anfordern und möglichst auf eine Website beschränkte persönliche Token verwenden.
• Für jeden logischen Schreibvorgang einen eigenen Idempotenzschlüssel verwenden und ihn bei Wiederholungen beibehalten.
• 401, 403, 404 und 422 als dauerhafte Fehler behandeln, sofern sich Anfrage oder Zugangsdaten nicht ändern.
• Bei vorübergehenden Fehlern exponentielles Backoff mit zufälliger Streuung verwenden und künftig vorhandene Retry-After-Header beachten.
• Sammlungsformate unterscheiden sich. Folgen Sie den dokumentierten Paginierungsdaten; nicht jedes Ergebnis ist eine flache oder unpaginierte Liste.