Riferimento API REST

EmDash espone la sua interfaccia di programmazione applicativa (API) supportata sotto /_emdash/api/. Usate il documento OpenAPI 3.1 generato per parametri di richiesta, body, schemi di risposta, codici di stato e generazione dei client:

GET /_emdash/api/openapi.json

Il documento è generato dagli stessi schemi Zod usati dall’API. Riflette anche la dimensione massima configurata per il caricamento dei media.

Limite del contratto pubblico

Il documento OpenAPI delimita l’API REST supportata. EmDash ha anche route per l’interfaccia admin e i flussi di protocollo. Una route presente nel codice sorgente ma assente da OpenAPI non è un’operazione REST supportata per i client esterni.

Questa distinzione vale per backup, amministrazione delle byline, attraversamento delle relazioni, gestione plugin, setup, import e route di autenticazione. Usate la guida ai backup per i backup e gli strumenti byline MCP per la gestione byline supportata. Gli endpoint OAuth sono endpoint di protocollo; scopriteli dai metadati descritti nella sezione MCP OAuth invece di trattarli come endpoint REST applicativi.

Autenticazione e autorizzazione

La maggior parte delle operazioni accetta un cookie di sessione EmDash o un token Bearer. Inviate un personal access token o un OAuth access token nell’header Authorization:

Authorization: Bearer $EMDASH_TOKEN

I token Bearer sono limitati dagli scope e dal ruolo dell’utente associato. Le richieste con sessione usano il ruolo dell’utente. Vedete ruoli utente e scope dei token per il modello di autorizzazione.

GET e POST /_emdash/api/comments/{collection}/{contentId} sono pubblici. L’operazione GET restituisce i commenti approvati; l’operazione POST invia un commento in moderazione. Le restanti operazioni di moderazione commenti richiedono autenticazione.

Protezione da cross-site request forgery

Per una richiesta che modifica lo stato autenticata con un cookie di sessione, includete questo header:

X-EmDash-Request: 1

Le richieste con token Bearer non richiedono l’header perché non usano credenziali implicite del browser. Le richieste del browser a un’operazione di scrittura pubblica devono inviare l’header oppure avere un Origin che corrisponda all’origine pubblica o di richiesta del sito EmDash.

Involucri di risposta

Una risposta JSON riuscita imposta success su true e colloca il risultato specifico dell’operazione in data:

{
	"success": true,
	"data": {
		"items": []
	}
}

In caso di errore, success è false e sono inclusi un codice stabile leggibile dalla macchina e un messaggio. Alcuni errori includono anche details strutturati:

{
	"success": false,
	"error": {
		"code": "NOT_FOUND",
		"message": "Content item not found"
	}
}

Usate i codici di stato e gli schemi di errore di ogni operazione OpenAPI. Gli stati comuni sono 400 per input non valido, 401 per credenziali mancanti o non valide, 403 per scope o permesso insufficiente, 404 per risorsa assente, 409 per conflitto di stato, 413 per upload troppo grande, 422 quando un plugin rifiuta il salvataggio e 500 per errore interno.

Inventario degli endpoint

L’ID operazione è stabile nel contratto generato ed è spesso usato come nome del metodo dai generatori di client OpenAPI. L’inventario seguente è verificato rispetto al documento OpenAPI generato.

Contenuti

Media

Schema

Commenti

Tassonomie

Menu

Sezioni

Widgets

Impostazioni

Ricerca

Reindirizzamenti

Utenti

Trasferimento

Ciclo di vita dei contenuti e byline

Il riferimento al ciclo di vita dei contenuti definisce stato, revisione, permessi, conflitti e comportamento degli hook condivisi da REST, MCP, CLI e pannello admin.

Le letture di contenuto restituiscono un token _rev opaco quando disponibile. Inviate _rev con PUT /content/{collection}/{id} per evitare di sovrascrivere una modifica avvenuta dopo la lettura. Un token obsoleto produce un conflitto; rileggete la voce prima di riprovare. La CLI rende obbligatorio questo controllo per content update, mentre il campo REST resta opzionale per i client che scelgono deliberatamente una scrittura incondizionata.

Leggere e aggiornare una voce

Leggete la voce prima di modificarla:

GET /_emdash/api/content/articles/01JARTICLE0000000000000000
Authorization: Bearer $EMDASH_TOKEN

La risposta contiene i campi, lo stato di pubblicazione e il token di revisione:

{
	"success": true,
	"data": {
		"item": {
			"id": "01JARTICLE0000000000000000",
			"type": "articles",
			"slug": "launch-notes",
			"status": "published",
			"data": { "title": "Launch notes" }
		},
		"_rev": "opaque-revision-token"
	}
}

Inviate solo i campi da modificare, insieme al token ottenuto con quella lettura:

PUT /_emdash/api/content/articles/01JARTICLE0000000000000000
Authorization: Bearer $EMDASH_TOKEN
Content-Type: application/json

{
	"data": { "title": "Updated launch notes" },
	"_rev": "opaque-revision-token"
}

Modificare una voce pubblicata crea una bozza mentre la versione precedente resta online. Usate l’operazione di confronto per rivedere entrambe le versioni, poi pubblicate la bozza o scartatela. Annullare la pubblicazione mantiene contenuto e data di pubblicazione, cancella eventuali pianificazioni in sospeso e rimuove la voce dal sito live.

I body di creazione e aggiornamento accettano crediti byline; le risposte di contenuto includono la byline principale e i crediti ordinati. L’elenco contenuti può filtrare per ID byline memorizzati e includere opzionalmente la byline dedotta di un autore. Creare e gestire i record byline avviene tramite gli strumenti byline MCP, non il contratto REST pubblico.

Le operazioni del ciclo di vita distinguono l’eliminazione soft da quella permanente. Il ripristino restituisce contenuti nel cestino come bozza senza pianificazione; l’eliminazione permanente rimuove una voce nel cestino e non è reversibile. Pubblicare, annullare pubblicazione, pianificare, annullare pianificazione, confrontare, scartare bozza e duplicare sono operazioni separate così i client possono richiedere una transizione di stato alla volta.

Blocco modifica voce

Le collection possono acquisire un blocco di modifica di sette minuti quando un editor apre una voce. Usate le tre operazioni su /content/{collection}/{id}/lock per leggere, acquisire o rinnovare e rilasciare il lease.

Una risposta di lettura o acquisizione indica se il blocco è attivo, se il chiamante detiene il lease e chi lo detiene attualmente:

{
	"success": true,
	"data": {
		"enabled": true,
		"heldByCaller": false,
		"holder": {
			"userId": "01JUSER000000000000000000",
			"userName": "Ada",
			"acquiredAt": "2026-05-01T09:12:04.117Z",
			"expiresAt": "2026-05-01T09:19:04.117Z"
		}
	}
}

Se una collection ha il blocco modifica disabilitato, enabled è false e nessun lease viene acquisito. Ri-acquisire lo stesso blocco e salvare la voce estendono entrambi un lease detenuto dal chiamante.

Il body di acquisizione può includere un token opaco che identifica una sessione di modifica e takeover: true quando l’utente sceglie di sostituire il lease di un altro editor. Passate lo stesso token come parametro di query al rilascio del blocco. Una seconda scheda dello stesso account non può rilasciare per errore il lease della prima.

Quando un altro utente detiene il lease, le scritture protette su contenuto restituiscono 409 ENTRY_LOCKED. I dettagli dell’errore identificano il detentore e la scadenza. Per ignorare il blocco, inviate "overrideLock": true nel body JSON di una scrittura con body, oppure ?overrideLock=true per un’operazione DELETE senza body.

Selezioni di riferimento

Un campo reference collega una voce a voci in un’altra collection tramite una relazione. Il suo valore non fa parte di data ed è indicizzato per gruppo di traduzione, quindi ogni traduzione di una voce condivide una selezione.

I body di creazione e aggiornamento portano le selezioni sotto references, indicizzate per slug del campo, ciascuna un array di al massimo 1000 ID voce in ordine di visualizzazione. EmDash scrive la selezione nella stessa transazione della voce. L’aggiornamento seguente sostituisce l’autore della voce:

PUT /_emdash/api/content/articles/01JARTICLE0000000000000000
Authorization: Bearer $EMDASH_TOKEN
Content-Type: application/json

{
	"data": { "title": "Updated launch notes" },
	"references": { "author": ["01JAUTHOR00000000000000000"] },
	"_rev": "opaque-revision-token"
}

Un campo legato all’estremità figlio della relazione seleziona le voci che puntano a quella scritta, senza ordine proprio. I limiti della relazione valgono su entrambe le estremità; una selezione che darebbe a una voce collegata più genitori di quanto la relazione consenta viene rifiutata come una che collega troppe voci.

Su una collection con revisioni, una selezione modificata su una voce pubblicata resta in bozza con le altre modifiche in sospeso. Diventa live alla pubblicazione e viene scartata con la bozza. La pubblicazione ricontrolla l’intera selezione rispetto ai limiti della relazione.

Una lettura singola restituisce references indicizzate per slug del campo. Ogni campo contiene la prima pagina delle voci collegate, 50 elementi, con nextCursor se ce ne sono altre, e riporta ID, slug, collection, titolo visualizzato, locale risolto e gruppo di traduzione di ogni voce. Un chiamante autorizzato a leggere bozze vede una selezione in staging se la bozza ne ha una. L’operazione di elenco contenuti non include i riferimenti.

Definizioni di relazione e attraversamento link sono route admin, assenti da OpenAPI e fuori dal contratto pubblico. Scrivete e leggete le selezioni tramite le operazioni contenuto sopra e renderizzatele sul sito con getEmDashEntry() e getEmDashReferences().

Traduzioni

Il contratto REST pubblico espone traduzioni di contenuto e definizioni di tassonomia. La creazione contenuto accetta translationOf; la creazione tassonomia usa lo stesso campo per aggiungere una variante di locale. Le operazioni content-term restituiscono assegnazioni sensibili al locale.

GET /taxonomies/{name} restituisce la definizione del locale predefinito del sito se locale è omesso, ricadendo sul codice locale più basso solo se il predefinito non ha definizione. Un aggiornamento si comporta diversamente: senza locale modifica la definizione con il codice locale più basso. Passate locale così un aggiornamento di tassonomia tradotta raggiunge la definizione prevista. Se quel locale non ha definizione, l’aggiornamento restituisce NOT_FOUND invece di ricadere su un altro locale. L’operazione translations restituisce ogni definizione nel gruppo condiviso e gli ID accettati da translationOf.

label e labelSingular appartengono alla definizione di un locale. hierarchical e collections appartengono alla tassonomia: ogni locale restituisce gli stessi valori e un aggiornamento che invia uno dei due li modifica per tutti i locale. Creare una definizione per un nome già presente in un altro locale la aggiunge a quella tassonomia, indipendentemente da translationOf nella richiesta. La nuova definizione eredita hierarchical e collections della tassonomia; una create con valori diversi restituisce VALIDATION_ERROR.

Eliminare una tassonomia rimuove ogni locale della definizione, tutti i termini e tutte le assegnazioni di quei termini al contenuto. Non elimina le voci di contenuto.

L’operazione di riordino termini modifica un gruppo di fratelli. L’array ids può contenere solo parte del gruppo; i termini elencati scambiano le posizioni esistenti e quelli omessi restano dove sono. Ad esempio, riordinare [A, B, C] con ids: ["C", "A"] produce [C, B, A]. Il riordino non cambia le relazioni genitore; un ordine termini vale per ogni locale nel suo gruppo di traduzione.

Le route di traduzione menu, termini tassonomia e byline non sono nel contratto REST pubblico. Gli elenchi supportati sono disponibili tramite menu_translations, taxonomy_term_translations e byline_translations sul server MCP.

Endpoint media

Le operazioni media coprono elenco, upload, aggiornamento metadati, sostituzione immagine, cartelle, informazioni d’uso e manutenzione dell’indice d’uso. La guida alla libreria media spiega il flusso per l’utente e il significato della copertura d’uso.

Elencare e ispezionare i media

GET /media supporta paginazione a cursore o a pagine numerate, filtri MIME e nome file, cartelle e riepiloghi d’uso opzionali. Omettete folderId per includere ogni cartella, oppure passate folderId=unfiled per solo la libreria principale. Impostate includeUsage=1 su elenco o lettura singola per le informazioni d’uso; qualsiasi altro valore non è valido.

usage.count conta righe contenuto attive distinte o locale il cui sorgente indicizzato corrente referenzia il media, più ogni impostazione sito che lo seleziona (logo, favicon, seo.defaultOgImage). Riferimenti ripetuti in una voce contano una volta; le voci nel cestino no. Il numero è visibile solo a chi può leggere bozze; altri lettori media autorizzati ricevono count: null perché il conteggio potrebbe rivelare contenuto bozza.

GET /media/{id}/usage restituisce a pagine le voci contenuto che referenziano il media. Ogni pagina include anche siteSettings, le impostazioni che selezionano il media, ad esempio [{ "setting": "favicon" }]. Le impostazioni sito sono lette dalle impostazioni memorizzate a ogni richiesta e non dipendono dall’indicizzazione d’uso.

Ogni risultato d’uso include uno stato di copertura:

Solo con complete si può trattare un conteggio zero come completo nei tipi di campo indicizzati. I conteggi sono indicativi durante scritture concorrenti; non bloccano il media né garantiscono che l’eliminazione sia sicura. L’indicizzazione d’uso copre campi immagine e file, campi immagine repeater, blocchi immagine e galleria Portable Text e media dichiarati da versioni blocco conservate nelle collection EmDash. Sono riportati anche logo sito, favicon e immagine social predefinita. L’uso non include blocchi Portable Text personalizzati, codice applicativo, HTML renderizzato, altre impostazioni, menu, widget, dati plugin, siti esterni o asset solo del provider.

Caricamento multipart diretto

Inviate un file tramite EmDash pubblicandolo come campo file di una richiesta multipart:

curl --request POST \
	--header "Authorization: Bearer $EMDASH_TOKEN" \
	--form "file=@./cover.jpg;type=image/jpeg" \
	https://example.com/_emdash/api/media

curl aggiunge il boundary multipart. Non impostate manualmente l’header Content-Type. Lo schema OpenAPI MediaDirectUploadBody elenca i campi metadati opzionali e gli schemi di risposta distinguono un nuovo upload da un elemento esistente deduplicato.

Il body multipart può includere anche width e height dell’immagine, un fieldId la cui allowlist di tipi MIME va applicata e una thumbnail ridimensionata usata per un segnaposto a bassa qualità. Un nuovo file restituisce 201 Created ed è subito pronto. Byte identici restituiscono il media esistente con 200 OK e deduplicated: true.

Flusso di destinazione upload

Usate il flusso di destinazione upload quando il client può caricare direttamente su storage compatibile S3. Il media resta in stato pending e non compare nella libreria standard finché la conferma non riesce.

Lo storage locale e R2 nativo restituiscono una destinazione upload EmDash same-origin. Lo storage compatibile S3 può restituire un URL esterno firmato. Gli elementi pending restano fuori dall’elenco media standard finché la conferma non riesce.

Errori di upload

I seguenti errori richiedono un’azione di recupero diversa:

Cartelle media

I nomi delle cartelle sono trimmati, limitati a 200 caratteri e confrontati dopo normalizzazione Unicode e minuscolizzazione. Nomi come Photos, photos e ＰＨＯＴＯＳ quindi entrano in conflitto. Eliminare una cartella restituisce i media alla libreria principale; non elimina media, non cambia ID o URL dei media né i record d’uso.

Riparare l’uso dei media

Attivazione, progresso, code di lavoro, pulizia eliminazioni e riparazione dell’uso media sono operazioni per operatori sotto /_emdash/api/admin/media-usage/. Gli utenti con sessione necessitano schema:manage; i token Bearer richiedono anche lo scope admin.

Se il tracciamento è disattivato, mettete in pausa gli scrittori diretti del database prima dell’attivazione. EmDash blocca temporaneamente le scritture di contenuto e schema inviate tramite le sue API durante il setup, ma non può fermare un altro processo che scrive direttamente nel database.

Se una richiesta di scrittura va in timeout o restituisce 409 o 500, leggete stato di attivazione e progresso prima di riprovare. I batch completati restano registrati. Quando lastErrorCode è impostato, tenete fermi gli scrittori diretti, risolvete il problema segnalato e inviate un retry confermato. L’attivazione non può essere annullata o reimpostata dopo l’avvio: testate la procedura su una copia di staging e mantenete un backup database aggiornato.

Le operazioni di elenco lavori espongono indicizzazioni voce fallite o ritardate senza restituire contenuto, riferimenti media, token di lease, errori DB grezzi o un conteggio esatto del backlog. Riprovare un elemento è idempotente. 409 WORK_LEASE_ACTIVE significa che un worker sta ancora elaborando l’elemento; la risposta include details.leaseExpiresAt: attendete fino a quell’istante e rileggete prima di riprovare. 409 WORK_CHANGED significa che un’altra richiesta ha modificato l’elemento di lavoro; leggete lo stato corrente invece di sovrascrivere il lavoro più recente.

L’operazione di riparazione accetta { "scope": "collection", "collection": "articles" } oppure { "scope": "all" }. Una riparazione su tutte le collection gira in modo sincrono e sequenziale e può richiedere molto tempo su siti grandi. Una risposta 200 può comunque segnalare partial, failed o stale; controllate data.status, lo stato per collection e i conteggi sorgente prima di considerare la riparazione completa.

Trasferimento sito

Le operazioni di trasferimento sotto /_emdash/api/admin/transfer/ esportano un sito come pacchetto sito e ne importano uno in un sito vuoto. La guida al trasferimento sito descrive export, upload, analisi, esecuzione e flusso di ricevuta.

Gli utenti con sessione necessitano del permesso transfer:export o transfer:import, riservato agli amministratori. I token Bearer richiedono admin o lo scope transfer:export, transfer:analyze o transfer:execute indicato da ogni operazione. Le operazioni di approvazione accettano solo sessioni autenticate. Decidono le richieste avviate dagli strumenti MCP site_export_start e site_import_start; le operazioni REST di export ed esecuzione non richiedono approvazione.

Mentre un import è in esecuzione, e dopo un fallimento o annullamento finché non viene abbandonato, la maggior parte delle altre operazioni di scrittura restituisce 503 TRANSFER_IMPORT_IN_PROGRESS. La guida elenca le operazioni che restano disponibili.

Paginazione

Le operazioni di elenco descrivono i parametri di paginazione in OpenAPI. La maggior parte delle operazioni con paginazione a cursore accetta un cursor opaco e un limit da 1 a 100, predefinito 50. Restituite il nextCursor della risposta precedente invariato; non analizzatelo né costruitelo. Alcune operazioni media supportano anche pagine numerate e alcuni elenchi specializzati usano limiti diversi: i client generati dovrebbero seguire lo schema di ogni operazione.

Tokenizer di ricerca

L’operazione di abilitazione ricerca memorizza un tokenizer per ogni collection. Modificarlo su una collection abilitata ricostruisce l’indice di quella collection.

Disabilitare la ricerca conserva il tokenizer memorizzato per la prossima abilitazione. L’operazione di rebuild usa il tokenizer memorizzato della collection e i pesi dei campi.

Commenti e reindirizzamenti

Le submission pubbliche di commenti entrano nella coda di moderazione. Le operazioni admin commenti elencano tutti gli stati, restituiscono conteggi, aggiornano uno stato, moderano in blocco ed eliminano definitivamente un commento. Una risposta 429 indica che è stato raggiunto il limite di frequenza di invio.

Le operazioni reindirizzamento gestiscono separatamente regole di reindirizzamento e log 404 registrato. La potatura rimuove le voci selezionate dal body della richiesta, mentre DELETE /redirects/404s svuota l’intero log. Nessuna delle due operazioni elimina le regole di reindirizzamento.