E EmDash CMS Everything Guides, use cases, plugins, templates
Italiano

Riferimento API REST

In questa pagina

EmDash espone un’API REST in /_emdash/api/ per la gestione dei contenuti, il caricamento dei media e le operazioni sugli schemi.

Autenticazione

Le richieste API richiedono l’autenticazione tramite un token Bearer nell’intestazione Authorization:

Authorization: Bearer <token>

Genera token tramite l’interfaccia di amministrazione o programmaticamente.

Formato della risposta

Tutte le risposte seguono un formato coerente. Una risposta riuscita avvolge il risultato in data:

{
  "success": true,
  "data": { ... }
}

Una risposta di errore include un codice, un messaggio e dettagli opzionali:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { ... }
  }
}

Endpoint dei Contenuti

Elencare i Contenuti

GET /_emdash/api/content/:collection

Parametri

ParametroTipoDescrizione
collectionstringSlug della collezione (percorso)
cursorstringCursore di paginazione (query)
limitnumberElementi per pagina (query, predefinito: 50)
statusstringFiltra per stato (query)
orderBystringCampo per ordinare (query)
orderstringDirezione di ordinamento: asc o desc (query)

Risposta

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "type": "posts",
        "slug": "hello-world",
        "data": { "title": "Hello World", ... },
        "status": "published",
        "createdAt": "2025-01-24T12:00:00Z",
        "updatedAt": "2025-01-24T12:00:00Z"
      }
    ],
    "nextCursor": "eyJpZCI6..."
  }
}

Ottenere il Contenuto

GET /_emdash/api/content/:collection/:id

Risposta

{
  "success": true,
  "data": {
    "item": {
      "id": "01HXK5MZSN...",
      "type": "posts",
      "slug": "hello-world",
      "data": { "title": "Hello World", ... },
      "status": "published",
      "createdAt": "2025-01-24T12:00:00Z",
      "updatedAt": "2025-01-24T12:00:00Z"
    }
  }
}

Creare un Contenuto

POST /_emdash/api/content/:collection
Content-Type: application/json

Corpo della Richiesta

{
  "data": {
    "title": "New Post",
    "content": [...]
  },
  "slug": "new-post",
  "status": "draft"
}

Risposta

{
  "success": true,
  "data": {
    "item": { ... }
  }
}

Aggiornare un Contenuto

PUT /_emdash/api/content/:collection/:id
Content-Type: application/json

Corpo della Richiesta

{
	"data": {
		"title": "Updated Title"
	},
	"status": "published"
}

Eliminare un Contenuto

DELETE /_emdash/api/content/:collection/:id

Risposta

{
	"success": true,
	"data": {
		"success": true
	}
}

Endpoint dei Media

Elencare i Media

GET /_emdash/api/media

Parametri

ParametroTipoDescrizione
cursorstringCursore di paginazione
limitnumberElementi per pagina (predefinito: 20)
mimeTypestringFiltra per prefisso tipo MIME

Risposta

{
	"success": true,
	"data": {
		"items": [
			{
				"id": "01HXK5MZSN...",
				"filename": "photo.jpg",
				"mimeType": "image/jpeg",
				"size": 102400,
				"width": 1920,
				"height": 1080,
				"url": "https://cdn.example.com/photo.jpg",
				"createdAt": "2025-01-24T12:00:00Z"
			}
		],
		"nextCursor": "eyJpZCI6..."
	}
}

Ottenere un Media

GET /_emdash/api/media/:id

Creare un Media

POST /_emdash/api/media
Content-Type: application/json

Corpo della Richiesta

{
	"filename": "photo.jpg",
	"mimeType": "image/jpeg",
	"size": 102400,
	"width": 1920,
	"height": 1080,
	"storageKey": "uploads/photo.jpg"
}

Aggiornare un Media

PUT /_emdash/api/media/:id
Content-Type: application/json

Corpo della Richiesta

{
	"alt": "Photo description",
	"caption": "Photo caption"
}

Eliminare un Media

DELETE /_emdash/api/media/:id

Ottenere il File Media

GET /_emdash/api/media/file/:key

Serve il contenuto del file effettivo. Solo per lo storage locale.

Endpoint delle Revisioni

Elencare le Revisioni

GET /_emdash/api/content/:collection/:entryId/revisions

Parametri

ParametroTipoDescrizione
limitnumberNumero massimo di revisioni (predefinito: 50)

Risposta

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "collection": "posts",
        "entryId": "01HXK5MZSN...",
        "data": { ... },
        "createdAt": "2025-01-24T12:00:00Z"
      }
    ],
    "total": 5
  }
}

Ottenere una Revisione

GET /_emdash/api/revisions/:revisionId

Ripristinare una Revisione

POST /_emdash/api/revisions/:revisionId/restore

Ripristina il contenuto allo stato di questa revisione e crea una nuova revisione.

Endpoint degli Schemi

Elencare le Collezioni

GET /_emdash/api/schema/collections

Risposta

{
	"success": true,
	"data": {
		"items": [
			{
				"id": "01HXK5MZSN...",
				"slug": "posts",
				"label": "Posts",
				"labelSingular": "Post",
				"supports": ["drafts", "revisions", "preview"]
			}
		]
	}
}

Ottenere una Collezione

GET /_emdash/api/schema/collections/:slug

Parametri

ParametroTipoDescrizione
includeFieldsbooleanIncludi definizioni dei campi (query)

Creare una Collezione

POST /_emdash/api/schema/collections
Content-Type: application/json

Corpo della Richiesta

{
	"slug": "products",
	"label": "Products",
	"labelSingular": "Product",
	"description": "Product catalog",
	"supports": ["drafts", "revisions"]
}

Aggiornare una Collezione

PUT /_emdash/api/schema/collections/:slug
Content-Type: application/json

Eliminare una Collezione

DELETE /_emdash/api/schema/collections/:slug

Parametri

ParametroTipoDescrizione
forcebooleanElimina anche se la collezione contiene contenuto (query)

Elencare i Campi

GET /_emdash/api/schema/collections/:slug/fields

Creare un Campo

POST /_emdash/api/schema/collections/:slug/fields
Content-Type: application/json

Corpo della Richiesta

{
	"slug": "price",
	"label": "Price",
	"type": "number",
	"required": true,
	"validation": {
		"min": 0
	}
}

Aggiornare un Campo

PUT /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug
Content-Type: application/json

Eliminare un Campo

DELETE /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug

Riordinare i Campi

POST /_emdash/api/schema/collections/:slug/fields/reorder
Content-Type: application/json

Corpo della Richiesta

{
	"fieldSlugs": ["title", "content", "author", "publishedAt"]
}

Esportazione dello Schema

Esportare lo Schema (JSON)

GET /_emdash/api/schema
Accept: application/json

Esportare lo Schema (TypeScript)

GET /_emdash/api/schema?format=typescript
Accept: text/typescript

Restituisce interfacce TypeScript per tutte le collezioni.

Endpoint dei Plugin

Elencare i Plugin

GET /_emdash/api/admin/plugins

Ottenere un Plugin

GET /_emdash/api/admin/plugins/:id

Abilitare un Plugin

POST /_emdash/api/admin/plugins/:id/enable

Disabilitare un Plugin

POST /_emdash/api/admin/plugins/:id/disable

Codici di Errore

CodiceStato HTTPDescrizione
NOT_FOUND404Risorsa non trovata
VALIDATION_ERROR400Dati di input non validi
UNAUTHORIZED401Token mancante o non valido
FORBIDDEN403Permessi insufficienti
CONTENT_LIST_ERROR500Errore nell’elencare i contenuti
CONTENT_CREATE_ERROR500Errore nella creazione del contenuto
CONTENT_UPDATE_ERROR500Errore nell’aggiornamento del contenuto
CONTENT_DELETE_ERROR500Errore nell’eliminazione del contenuto
MEDIA_LIST_ERROR500Errore nell’elencare i media
MEDIA_CREATE_ERROR500Errore nella creazione del media
SCHEMA_CREATE_ERROR500Operazione sullo schema fallita
SLUG_CONFLICT409Lo slug esiste già
RESERVED_SLUG400Lo slug è riservato

Endpoint di Ricerca

Ricerca Globale

GET /_emdash/api/search?q=hello+world

Parametri

ParametroTipoDescrizione
qstringQuery di ricerca (richiesto)
collectionsstringSlug di collezioni separati da virgole
statusstringFiltra per stato (predefinito: published)
limitnumberRisultati massimi (predefinito: 20)
cursorstringCursore di paginazione

Risposta

{
  "success": true,
  "data": {
    "items": [
      {
        "collection": "posts",
        "id": "01HXK5MZSN...",
        "slug": "hello-world",
        "locale": "en",
        "title": "Hello World",
        "snippet": "...this is a <mark>hello</mark> <mark>world</mark> example...",
        "score": 0.95
      }
    ],
    "nextCursor": "eyJvZmZzZXQiOjIwfQ"
  }
}

Suggerimenti di Ricerca

GET /_emdash/api/search/suggest?q=hel&limit=5

Restituisce titoli corrispondenti al prefisso per l’autocompletamento.

Ricostruire l’Indice di Ricerca

POST /_emdash/api/search/rebuild

Ricostruisce l’indice FTS per tutte le collezioni o collezioni specifiche.

Statistiche di Ricerca

GET /_emdash/api/search/stats

Restituisce i conteggi dei documenti indicizzati per collezione.

Endpoint delle Sezioni

Elencare le Sezioni

GET /_emdash/api/sections
GET /_emdash/api/sections?source=theme
GET /_emdash/api/sections?search=newsletter

Ottenere una Sezione

GET /_emdash/api/sections/:slug

Creare una Sezione

POST /_emdash/api/sections
Content-Type: application/json

{
  "slug": "my-section",
  "title": "My Section",
  "keywords": ["keyword1"],
  "content": [...]
}

Aggiornare una Sezione

PUT /_emdash/api/sections/:slug

Eliminare una Sezione

DELETE /_emdash/api/sections/:slug

Endpoint delle Impostazioni

Ottenere Tutte le Impostazioni

GET /_emdash/api/settings

Aggiornare le Impostazioni

POST /_emdash/api/settings
Content-Type: application/json

{
  "siteTitle": "My Site",
  "tagline": "A great site",
  "postsPerPage": 10
}

Endpoint dei Menu

Elencare i Menu

GET /_emdash/api/menus

Ottenere un Menu

GET /_emdash/api/menus/:name

Creare un Menu

POST /_emdash/api/menus
Content-Type: application/json

{
  "name": "footer",
  "label": "Footer Navigation"
}

Aggiornare un Menu

PUT /_emdash/api/menus/:name

Eliminare un Menu

DELETE /_emdash/api/menus/:name

Aggiungere un Elemento del Menu

POST /_emdash/api/menus/:name/items
Content-Type: application/json

{
  "type": "page",
  "referenceCollection": "pages",
  "referenceId": "page_about",
  "label": "About Us"
}

Riordinare gli Elementi del Menu

POST /_emdash/api/menus/:name/reorder
Content-Type: application/json

{
  "items": [
    { "id": "item_1", "parentId": null, "sortOrder": 0 },
    { "id": "item_2", "parentId": null, "sortOrder": 1 },
    { "id": "item_3", "parentId": "item_2", "sortOrder": 0 }
  ]
}

Endpoint delle Tassonomie

Elencare le Definizioni di Tassonomie

GET /_emdash/api/taxonomies

Creare una Tassonomia

POST /_emdash/api/taxonomies
Content-Type: application/json

{
  "name": "genre",
  "label": "Genres",
  "labelSingular": "Genre",
  "hierarchical": true,
  "collections": ["books", "movies"]
}

Elencare i Termini

GET /_emdash/api/taxonomies/:name/terms

Creare un Termine

POST /_emdash/api/taxonomies/:name/terms
Content-Type: application/json

{
  "slug": "tutorials",
  "label": "Tutorials",
  "parentId": "term_abc",
  "description": "How-to guides"
}

Aggiornare un Termine

PUT /_emdash/api/taxonomies/:name/terms/:slug

Eliminare un Termine

DELETE /_emdash/api/taxonomies/:name/terms/:slug

Impostare i Termini di Voce

POST /_emdash/api/content/:collection/:id/terms/:taxonomy
Content-Type: application/json

{
  "termIds": ["term_news", "term_featured"]
}

Endpoint delle Aree Widget

Elencare le Aree Widget

GET /_emdash/api/widget-areas

Ottenere un’Area Widget

GET /_emdash/api/widget-areas/:name

Creare un’Area Widget

POST /_emdash/api/widget-areas
Content-Type: application/json

{
  "name": "sidebar",
  "label": "Main Sidebar",
  "description": "Appears on posts"
}

Eliminare un’Area Widget

DELETE /_emdash/api/widget-areas/:name

Aggiungere un Widget

POST /_emdash/api/widget-areas/:name/widgets
Content-Type: application/json

{
  "type": "content",
  "title": "About",
  "content": [...]
}

Aggiornare un Widget

PUT /_emdash/api/widget-areas/:name/widgets/:id

Eliminare un Widget

DELETE /_emdash/api/widget-areas/:name/widgets/:id

Riordinare i Widget

POST /_emdash/api/widget-areas/:name/reorder
Content-Type: application/json

{
  "widgetIds": ["widget_1", "widget_2", "widget_3"]
}

Endpoint di Gestione Utenti

Elencare gli Utenti

GET /_emdash/api/admin/users
GET /_emdash/api/admin/users?role=40
GET /_emdash/api/admin/users?search=john

Ottenere un Utente

GET /_emdash/api/admin/users/:id

Aggiornare un Utente

PUT /_emdash/api/admin/users/:id
Content-Type: application/json

{
  "name": "John Doe",
  "role": 40
}

Abilitare un Utente

POST /_emdash/api/admin/users/:id/enable

Disabilitare un Utente

POST /_emdash/api/admin/users/:id/disable

Endpoint di Autenticazione

Stato di Configurazione

GET /_emdash/api/setup/status

Restituisce se la configurazione è completa e se esistono utenti.

Login con Passkey

POST /_emdash/api/auth/passkey/options

Ottiene le opzioni di autenticazione WebAuthn.

POST /_emdash/api/auth/passkey/verify
Content-Type: application/json

{
  "id": "credential-id",
  "rawId": "...",
  "response": {...},
  "type": "public-key"
}

Verifica la passkey e crea la sessione.

POST /_emdash/api/auth/magic-link/send
Content-Type: application/json

{
  "email": "user@example.com"
}
GET /_emdash/api/auth/magic-link/verify?token=xxx

Logout

POST /_emdash/api/auth/logout

Utente Corrente

GET /_emdash/api/auth/me

Invitare un Utente

POST /_emdash/api/auth/invite
Content-Type: application/json

{
  "email": "newuser@example.com",
  "role": 30
}

Gestione delle Passkey

GET /_emdash/api/auth/passkey

Elenca le passkey dell’utente.

POST /_emdash/api/auth/passkey/register/options
POST /_emdash/api/auth/passkey/register/verify

Registra una nuova passkey.

PATCH /_emdash/api/auth/passkey/:id
Content-Type: application/json

{
  "name": "MacBook Pro"
}

Rinomina la passkey.

DELETE /_emdash/api/auth/passkey/:id

Elimina la passkey.

Endpoint di Importazione

Analizzare l’Esportazione WordPress

POST /_emdash/api/import/wordpress/analyze
Content-Type: multipart/form-data

file: <WXR file>

Eseguire l’Importazione WordPress

POST /_emdash/api/import/wordpress/execute
Content-Type: application/json

{
  "analysisId": "...",
  "options": {
    "includeMedia": true,
    "includeTaxonomies": true,
    "includeMenus": true
  }
}

Limitazione della Frequenza

Gli endpoint dell’API possono essere soggetti a limitazione della frequenza in base alla configurazione del deployment. Quando viene applicata la limitazione, le risposte includono:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

CORS

L’API supporta CORS per le richieste del browser. Configura le origini consentite nel tuo deployment.