Crea con Eyivo attraverso un’unica API strutturata.

1. Panoramica

L’API REST di Eyivo consente di gestire programmaticamente siti web strutturati. Usa HTTPS e JSON, è versionata sotto /api/v1 e applica gli stessi vincoli di proprietà, limiti del piano, regole di convalida e controlli di audit della dashboard.

Versionamento: le modifiche incompatibili del contratto richiedono una nuova versione di base. Nei JSON esistenti possono comparire nuovi campi; i client devono ignorare quelli che non riconoscono.

2. Guida rapida

1. 1
   Crea un token.

   Accedi all’app, apri Token API, scegli solo gli ambiti necessari e copia il ey_ segreto quando viene mostrato.

2. 2
   Elenca i tuoi siti.

   Conferma l’autenticazione e ottieni l’ID numerico del sito usato dagli endpoint nidificati.

3. 3
   Invia richieste di scrittura idempotenti.

   Assegna a ogni richiesta POST, PATCH e DELETE una Idempotency-Key.

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

Una risposta riuscita per una raccolta contiene i record in 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. Autenticazione

Ogni richiesta a /api/v1 richiede un bearer token:

Authorization: Bearer <token>

Flusso di autorizzazione PKCE

1. Crea un code_verifier ad alta entropia e il relativo code_challenge SHA-256.
2. Reindirizza l’utente a /oauth/authorize includendo response_type=code, il client_id pubblico, il redirect_uri registrato esatto, gli ambiti richiesti in scope separati da spazi, state, code_challenge e code_challenge_method=S256.
3. Verifica state dopo il reindirizzamento, quindi scambia il codice di autorizzazione ricevuto su /oauth/token usando il code_verifier originale.
4. Conserva access token e refresh token in modo sicuro. Rinnovali prima della scadenza e sostituisci atomicamente le credenziali ruotate.

4. Ambiti di accesso

Le richieste richiedono l’ambito di accesso esatto indicato di seguito. Un token personale che contiene * supera tutti i controlli sugli ambiti; le applicazioni dovrebbero comunque richiedere solo quelli necessari.

REST richiede l’autorizzazione dell’endpoint, non mcp:use. I media usano media:read o media:write.

5. Operazioni di scrittura idempotenti

Invia Idempotency-Key nelle modifiche JSON per ripetere la stessa richiesta in sicurezza. I caricamenti multipart e l’emissione dei ticket sono esclusi; verifica il risultato prima di riprovare.

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

Per corrispondere, le richieste devono avere lo stesso metodo HTTP, percorso e corpo grezzo. Quando riprovi, riutilizza il JSON serializzato originale.

6. Risposte e struttura delle risorse

Le operazioni restituiscono un contenitore data. MCP fornisce structuredContent e una copia JSON testuale; REST restituisce JSON. Consulta gli schemi per ID, stato di pubblicazione e paginazione. Segui le informazioni di pagina di blog, media e invii.

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

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

I formati delle raccolte variano. Segui la paginazione documentata da ogni endpoint; non tutti i risultati sono liste semplici o senza paginazione.

7. Siti

Crea un sito

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"
  }'

Risposta: 201 Created con una risorsa sito. Durante la preparazione, lo stato può inizialmente risultare non attivo. I limiti relativi a siti e piano restituiscono 422.

Campi della risorsa sito: id, platform_subdomain_key, template_key, status, native_locale, english_enabled, content_version, search_visibility, runtime facoltativo e timestamp.

8. Pagine

Crea una pagina

{
  "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."
}

Risposta alla creazione: 201. Risposta alla modifica: 200. Risposta all’eliminazione: 204 senza corpo.

Salva una bozza, verifica che sia pronta e pubblica l’elemento nella lingua richiesta quando l’utente vuole renderlo visibile. Le altre bozze non vengono pubblicate.

9. Elementi del catalogo

Crea un elemento del catalogo

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

Salva una bozza, verifica che sia pronta e pubblica l’elemento nella lingua richiesta quando l’utente vuole renderlo visibile. Le altre bozze non vengono pubblicate.

Questi sono esempi per famiglia di contenuti. Scopri tutti gli schemi e le autorizzazioni in tools/list o OpenAPI. I percorsi REST sono relativi a /api/v1/sites/{site}.

Capacità e contratto di modifica

Seleziona un sito e leggi le sue capacità: lingue attive, campi del tema, schemi dei componenti, menu e pannelli dei plugin. Leggi la risorsa content-workflow prima di modificare. Senza risorse, usa get-site-capabilities-tool. Segui nextCursor di tools/list fino alla fine.

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

Usa la lingua richiesta e la version o revision corrente. Salvare un articolo sostituisce il documento completo e annulla la programmazione. I menu usano revision numerica; le assegnazioni un hash menu_revision separato. Conserva gli elementi delle liste sostituite. In caso di conflitto, rileggi e unisci le modifiche.

La navigazione principale resta automatica. I menu aggiuntivi hanno bozze e pubblicazioni proprie. Salvare un contenuto prepara le assegnazioni; pubblicare l’elemento le applica senza pubblicare altri menu. Pubblicare un menu non pubblica mai i contenuti collegati. source_hash rifiuta traduzioni basate su testo sorgente obsoleto.

Il corpo delle pagine e i campi richtext accettano HTML sanificato. list-page-links-tool fornisce link stabili /__eyivo/pages/{id}, risolti nella lingua del visitatore dopo la pubblicazione. I blog usano document JSON strutturato con media_id dello stesso sito e destinazioni pagina/articolo, non body_html.

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

Caricare immagini e video

upload-media-tool apre un selettore di file nei client MCP Apps come Claude. ChatGPT può fornire anche il proprio riferimento all’allegato; un allegato Claude non è un riferimento OpenAI. Non inventare URL né inviare file base64 negli argomenti.

Codex e Claude Code possono chiamare prepare-media-upload-tool e inviare il file multipart a upload_url con upload_token monouso entro cinque minuti. Mantieni segreto il token. I client REST possono usare il proprio bearer media:write. Solo il caricamento completato restituisce l’ID del media; emettere un ticket non carica file.

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. Domini personalizzati

Richiedi un dominio

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"}'

Una risorsa dominio in attesa include verification_token. Aggiungi il record DNS di verifica della proprietà usando il valore restituito per il tuo dominio, attendi la propagazione DNS, quindi chiama l’endpoint di attivazione. Dopo l’attivazione, chiama l’endpoint per il dominio principale se vuoi renderlo il nome host pubblico canonico.

Campi della risorsa dominio: id, domain, site_id, is_primary, status, verification_token quando applicabile e timestamp. I limiti del piano per i domini personalizzati e gli errori di convalida del dominio restituiscono 422.

11. Errori

Risposta di convalida

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

Risposta di autenticazione o autorizzazione

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

12. Limiti attuali e lista di controllo per le integrazioni

REST v1 espone intenzionalmente un insieme limitato di funzionalità di Eyivo. L’assenza di un endpoint è un limite dell’interfaccia pubblica, non un permesso di chiamare le API interne.

Prima di andare in produzione

• Usa HTTPS e verifica che l’host sia app.eyivo.com.
• Conserva i bearer token lato server e oscura gli header di autorizzazione nei log.
• Richiedi solo gli ambiti necessari e, quando possibile, preferisci token personali limitati a un sito.
• Usa una chiave di idempotenza univoca per ogni operazione logica di scrittura e mantienila nei tentativi successivi.
• Considera 401, 403, 404 e 422 errori non temporanei, salvo che cambi la richiesta o la credenziale.
• Per gli errori temporanei usa un intervallo di attesa esponenziale con jitter e rispetta un eventuale header Retry-After.
• I formati delle raccolte variano. Segui la paginazione documentata da ogni endpoint; non tutti i risultati sono liste semplici o senza paginazione.