API di Edgepedia
Oltre 500.000 articoli enciclopedici, in costante aumento, in formato JSON. Gratis. Senza chiavi né registrazione. Uso commerciale con attribuzione. Addestramento dell’IA aperto a tutti.
Provala
- www.edgepedia.org/api/v1/search?q=koala
- www.edgepedia.org/api/v1/articles/koala
- www.edgepedia.org/api/v1/random
- www.edgepedia.org/api/v1/topics
Gli endpoint di lettura usano GET; quelli per la migrazione, le operazioni in batch e i testi inviati usano POST. Ogni endpoint restituisce JSON a qualsiasi programma o pagina web (CORS consente tutte le origini). Descrizione leggibile dalle macchine: /openapi.json, con una risposta di esempio per ogni endpoint; la stessa descrizione in OpenAPI 3.0, le definizioni delle funzioni per i modelli, i tipi TypeScript e le raccolte di richieste sono elencati più avanti, in File generati.
Schede di riferimento
Articolo selezionato: Cantor's diagonal argument
Il titolo di una voce, la sintesi completa e l’attribuzione a Edgepedia, in una scheda per il tuo sito.
/embed/{id}?theme=auto fornisce una scheda a partire dall’ID canonico della voce. L’aspetto può essere auto, light o dark. Lo script facoltativo /assets/edgepedia-embed.js adatta il riquadro al contenuto; senza, il riquadro resta leggibile e scorrevole.
Funziona anche /embed/{slug}: reindirizza alla scheda corrispondente all’ID della voce, mantenendo il tema. Edgepedia è anche un provider oEmbed: GET /oembed?url={article or card URL}&format=json restituisce in html lo stesso codice di incorporamento generato dallo strumento qui sopra, con titolo, larghezza e altezza; maxwidth e maxheight vengono rispettati. Ogni pagina di una voce di General include nel proprio <head> un collegamento al suo indirizzo oEmbed, così WordPress, Discourse e gli altri sistemi che utilizzano oEmbed trasformano un link di Edgepedia incollato nel testo in una scheda.
Endpoint
| Endpoint | Restituisce |
|---|---|
/api/v1/search?q=words | Corrispondenze con titoli e altri nomi, a partire dalle più pertinenti. Cerca il nome di un soggetto, non una domanda. Ogni risultato contiene: id, titolo, argomento di primo livello, testo di anteprima, link e tipo di corrispondenza (match, confidence). Le espressioni che indicano un argomento, come «science fiction writers», restituiscono anche topics, un link alle relative voci. limit è il numero di risultati per pagina, da 1 a 30 (valore predefinito: 10); page permette di passare da una pagina all’altra, e una pagina oltre l’ultima è vuota. Funzionano anche altri nomi e gli errori di ortografia: «zhu yuanzhang» trova l’imperatore Hongwu e «siddartha» restituisce did_you_mean. Altre opzioni: Ricerca, più avanti. |
/api/v1/articles/{slug} | La voce in Markdown, il suo percorso nell’albero degli argomenti, le sue posizioni nell’albero geografico (geo), la data dell’ultimo aggiornamento e la riga di attribuzione da mostrare. Funziona con qualsiasi nome (Mount_Fuji, un titolo, un indirizzo completo); le opzioni permettono di ottenere una sezione, una struttura, dei passaggi o altri formati: Lettura di una voce, più avanti. |
/api/v1/articles?id={id} | Gli stessi dati, tramite id. I vecchi id delle voci continuano a essere risolti dopo una migrazione del corpus; gli id degli argomenti possono cambiare quando l’albero viene rivisto. Un indirizzo può cambiare; quello vecchio continua a rispondere, con moved_from. ids= ne accetta fino a 10 alla volta. |
/api/v1/leads?ids={id},{id} | Fino a 50 voci tramite id, ciascuna nel formato di un risultato di ricerca (id, titolo, argomento di primo livello, testo di anteprima, link), per una pagina di schede. Gli id migrati o accorpati restituiscono la voce risultante, usando come chiave l’id richiesto; il valore id del risultato è quello canonico. Gli id sconosciuti o non disponibili vengono omessi. |
/api/v1/random | Una voce casuale. new=1 sceglie fra le voci più recenti; topic= o geo= sceglie fra quelle che discendono da un nodo. |
/api/v1/related/{slug} | Le voci vicine a una voce, con una sola chiamata: fino alle 10 più vicine nello stesso argomento, 3 per ciascuno di un massimo di 8 argomenti vicini e fino alle 10 più vicine in ciascun nodo geografico a cui appartiene. Anche ?id={id}. by=links restituisce invece le voci citate insieme a essa. |
/api/v1/topics | La radice dell’albero degli argomenti. |
/api/v1/topics/{id} | Il percorso di un argomento, i suoi sottoargomenti con il numero di voci e tutte le voci che ne discendono, 30 per pagina. format=mermaid ne disegna il sottoalbero. |
/api/v1/geo | L’albero geografico: le sue regioni, ciascuna con i propri periodi. |
/api/v1/geo/{id} | Un nodo geografico, con la stessa struttura di un argomento: il suo percorso, i nodi più specifici e le voci, 30 per pagina. Una regione elenca solo i propri periodi. |
POST /api/v1/ids/translate | Con la migrazione v1.5 abilitata: invia {"ids":["old-id", "another-id"]} (fino a 500 id distinti). La risposta associa gli id spostati agli id canonici risultanti; gli id invariati o sconosciuti vengono omessi. Salva lo stato di avanzamento dei batch completati e rispetta Retry-After. |
Il testo di anteprima usa l’estratto del corpus, quando disponibile, e altrimenti l’inizio della voce. I record e i risultati dotati di un estratto lo includono anche come snippet; markdown resta il testo completo della voce. node, quando presente, è il nodo attuale della voce nell’albero dei concetti.
Ogni voce è disponibile anche in Markdown al proprio indirizzo. Aggiungi .md: www.edgepedia.org/koala.md.
Server MCP
https://www.edgepedia.org/mcp. Aggiungilo a Claude come connettore personalizzato, a ChatGPT con la modalità sviluppatore attiva, a VS Code o Cursor con un clic, oppure a qualsiasi altro client MCP tramite il suo indirizzo. Senza chiavi né accesso. Cinque strumenti di sola lettura: search (riceve il nome di un soggetto e restituisce le voci corrispondenti, oltre a un argomento quando le parole ne indicano uno), fetch (una voce in Markdown, con riga di attribuzione, percorso nell’albero degli argomenti e collocazione geografica; citations: false per un testo più breve di circa un quarto; un id topic: elenca l’argomento superiore, gli argomenti più specifici e le voci di quell’argomento, 120 per page; topic:root e topic:geo sono le radici dell’albero degli argomenti e dell’albero geografico), related (le voci vicine a una voce nel suo argomento, negli argomenti vicini e nella geografia; by: "links" per le voci citate insieme a essa), connect (from, to: la catena di link fra due voci, così come la restituisce /api/v1/path) e resolve (name, con context e type facoltativi: la voce a cui più probabilmente si riferisce un nome, così come la restituisce /api/v1/resolve). Quando nessun titolo corrisponde a una ricerca search, dopo le corrispondenze nei titoli vengono restituite le voci il cui testo corrisponde: sono contrassegnate da match: fulltext, rientrano in limit e sono conteggiate in pages. Un errore dello strumento è un testo letto dal modello (con gli id di did_you_mean se l’id non appartiene ad alcuna voce); il suo codice viene trasmesso in _meta["ai.edgechat/error"], mai in structuredContent. fetch con links: "in" accetta links_page per ottenere le successive 30 voci che rimandano a quella voce.
search accetta limit (da 1 a 30, valore predefinito: 10), page, first, topic e sort, e restituisce page e pages; fetch accetta le opzioni per le voci indicate più avanti e ids per ottenerne più di una alla volta. Ogni risultato contiene canonical_id, l’id permanente della voce: fetch lo accetta e, quando un id o un indirizzo salvato è cambiato, fetch restituisce la voce con moved_from impostato sul valore richiesto. I risultati indicano la versione del corpus in _meta.corpus_version. I client che usano il protocollo 2025-06-18 o successivo ricevono anche un resource_link per ogni voce.
Risorse: edgepedia://article/{slug} (una voce in Markdown, lo stesso testo di fetch) e edgepedia://topic/{id} (gli argomenti più specifici e le voci di un argomento), entrambe con completamento; il completamento suggerisce anche titoli di voci per qualsiasi argomento di funzione che indichi una voce. Anche l’Agent Skill è disponibile tramite MCP (skills/list, skills/get), come skill://edgepedia/SKILL.md. Una richiesta GET a /mcp restituisce la scheda del server in JSON. I client che accettano solo text/event-stream ricevono ogni risposta come un singolo evento SSE message. Lo sha256 dell’elenco degli strumenti viene trasmesso nel _meta di ogni risposta (ai.edgechat/tools-sha256), rendendo così visibile ogni modifica alla descrizione di uno strumento.
Windows (anteprima, build 26220.7262 o successiva): odr.exe mcp add --uri https://www.edgepedia.org/mcp. Righe di configurazione per tutti gli altri client, un’Agent Skill ed esempi: github.com/EdgePlat/edgepedia-mcp.
Niente MCP, oppure un client che supporta solo il vecchio trasporto SSE? Fornisci al tuo modello due funzioni che chiamino /api/v1/search e /api/v1/articles/{slug}, oppure prendile già pronte da /tools.json. Gli indirizzi del vecchio trasporto (/sse, /mcp/sse) rispondono con 404 e un corpo che indica https://www.edgepedia.org/mcp.
Limiti
600 richieste al minuto e 100.000 al giorno per indirizzo IP, sia per l’API sia per il server MCP. Ogni risposta indica entrambe le finestre temporali in RateLimit-Policy. Oltre questi limiti, l’API risponde con 429, Retry-After e RateLimit; una chiamata a uno strumento MCP restituisce un errore dello strumento il cui retry_after indica i secondi. I conteggi sono mantenuti per singola istanza del server, quindi sono un tetto sotto cui restare, non un contatore esatto. Usa la cache. La traduzione degli id (/api/v1/ids/translate) conteggia separatamente ogni id richiesto; anche i batch /leads che verificano i vecchi id vengono conteggiati per ciascun vecchio id. Gli altri batch conteggiano ogni id o nome come una richiesta, mentre annotate conta una richiesta ogni 1.000 caratteri.
Licenza
Edgepedia Community License 1.0: gratuita con attribuzione, uso commerciale incluso. L’addestramento dell’IA è aperto a tutti e l’output di un modello non richiede attribuzione. Per gli altri usi, le organizzazioni con ricavi superiori a 100 milioni di dollari statunitensi o più di 100 milioni di utenti mensili devono stipulare una licenza separata.
Attribuzione: mostra la riga credit di ogni voce, con il relativo link, ovunque ne mostri il testo. Le risposte relative alle voci la includono anche pronta da incollare in credit_md e credit_html, e in license.spdx (LicenseRef-Edgepedia-Community-1.0). Le risposte dell’API per le voci e per /leads includono Link: <https://www.edgepedia.org/edgepedia/license>; rel="license" e X-License: LicenseRef-Edgepedia-Community-1.0.
L’app EdgeChat, le sue Edge Apps e il nostro software sono gratuiti ma proprietari: il codice sorgente non viene fornito e non è consentito copiarli, modificarli o ridistribuirli (Contratto di licenza di EdgeChat).
Errori
JSON: { "error": { "code": "not_found", "message": "…" } }. 400 manca q, 404 non trovato, 410 rimosso, 413 testo troppo lungo, 429 troppe richieste, 503 riprova. Una risposta 404 indica la chiamata successiva: hint, next (un URL) e, per l’indirizzo di una voce che non restituisce nulla, did_you_mean con i tre titoli più vicini. L’errore di risorsa non trovata dello strumento MCP fetch contiene lo stesso did_you_mean.
Modifiche
La versione 1 mantiene la propria struttura: è possibile aggiungere campi, ma mai rinominarli o rimuoverli. Le modifiche di Edgepedia sono elencate in /edgepedia/updates. Quando una versione riorganizza l’albero degli argomenti, come è avvenuto con la 1.8.0, l’id di un argomento spostato risponde con 301 e il nuovo id, e /api/v1/changes?since=<release> elenca tutte le voci aggiunte, modificate, spostate o rimosse da quella versione in poi.
/api/v1 riporta corpus_version, corpus_updated e release_notes. Questi identificano la versione pubblicata del corpus General e la sua data di pubblicazione, non la data dell’ultima modifica di ciascuna voce. Gli stessi metadati compaiono nelle istruzioni del server MCP. Le versioni del corpus non modificano la versione del software dell’API o di MCP. In quella risposta, id_policy indica quali garanzie offre un id: una versione può rinumerare o accorpare gli id, come ha fatto la 1.5, e i vecchi id continuano a rispondere, tramite un 308 e POST /api/v1/ids/translate.
Qualcosa non funziona? Segnalalo.
Riferimento
Gli endpoint e i campi che leggono dati derivati (importanza, livelli di leggibilità, link, date, altri nomi e indice di ricerca a testo integrale) rispondono con 503 e Retry-After, oppure omettono il campo, finché tali dati non vengono pubblicati insieme all’archivio.
Lettura di una voce
/api/v1/articles/{slug} e lo strumento MCP fetch accettano queste opzioni; senza, la risposta contiene l’intera voce.
| Opzione | Restituisce |
|---|---|
section={heading} | Una sezione, individuata dal titolo o da una sua parola (section=etymology trova «Name and etymology»; section=lead è la parte iniziale), con le relative sottosezioni. Un titolo sconosciuto produce una risposta 404 con sections della voce. |
outline=1 | outline: tutti i titoli con le rispettive dimensioni in token. |
max_tokens={n} | Il testo troncato a circa n token in corrispondenza della fine di una sezione o di un paragrafo, con tokens_estimate, truncated e next_cursor; passa quest’ultimo come cursor con lo stesso max_tokens per ottenere il resto. |
length=snippet, length=lead | L’estratto, oppure il titolo e il paragrafo iniziale, al posto dell’intero testo. |
format=text, html, jsonld, turtle, tables | La risposta come testo semplice, corpo renderizzato oppure rappresentazione JSON-LD o Turtle dei suoi campi pubblici; tables restituisce ogni tabella come columns e rows, come csv e con le citazioni spostate in cites e sources. |
chunks=1 | chunks: la voce suddivisa in paragrafi, ciascuno con un id stabile ricavato dal percorso dei titoli (geology-2) e un cite_url. |
q={words}&k={1–10} | passages: i k paragrafi (valore predefinito: 3) che corrispondono meglio alle parole, ciascuno con un cite_url. |
quote={sentence or chunk id} | cite_url: l’indirizzo della voce con un frammento di testo che apre la pagina in corrispondenza di quel passaggio; quote_found indica se la voce lo contiene. |
cite={format} | cite: un riferimento alla voce, così come lo restituisce /api/v1/cite. |
Ogni risposta relativa a una voce contiene anche speakable (l’estratto in una forma leggibile da un assistente vocale). importance e rank (PageRank calcolato sui link fra le voci; 1 indica la voce più centrale; è un conteggio dei link, non un giudizio sul soggetto), words, reading_grade (Flesch-Kincaid) e reading_minutes compaiono solo se fields= li specifica (?fields=title,importance,rank); lo strumento MCP fetch li include sempre. next=1 aggiunge fino a 5 voci da leggere in seguito. citations=false sostituisce i link alle fonti nel testo con richiami [n], in markdown, chunks e passages, come fa citations: false in MCP. Un indirizzo che non appartiene ad alcuna voce viene interpretato come id di una voce (/api/v1/articles/ep7rbwcy0a) o come titolo, senza distinguere maiuscole, minuscole e accenti (/api/v1/articles/paris); un indirizzo in minuscolo con trattini che si discosta ulteriormente restituisce 404, a meno che non si aggiunga ?suggest=1, mentre un indirizzo con maiuscole, spazi o trattini bassi (/api/v1/articles/Albert_Einstein) viene interpretato come un nome, quindi una corrispondenza approssimativa restituisce il miglior risultato di ricerca con resolved_by: search. Quando il nome fornito non è l’indirizzo della voce, la risposta indica come è stato interpretato (resolved_from, resolved_by: indirizzo, titolo o ricerca) ed elenca le altre 3 voci nearest. /api/v1/articles?ids={slug or id},{name} ne restituisce fino a 10 come articles (ciascuna con il nome a cui risponde in asked) e missing; ogni opzione si applica a ciascuna voce.
Citare una voce
/api/v1/cite/{slug}?format= fornisce un riferimento bibliografico in csl (CSL-JSON, il formato predefinito), bibtex, ris, apa, mla, chicago o harvard, con la riga di attribuzione come testo, Markdown e HTML; /api/v1/cite?ids={id},{slug} fa lo stesso per un massimo di 50 voci. L’autore è Edgepedia (EdgeChat); APA, MLA, Chicago e Harvard contrassegnano il titolo in corsivo con asterischi, come in Markdown. Le schede di riferimento contengono la stessa citazione in forma non visibile, come COinS e JSON-LD, per i gestori bibliografici.
Ricerca
match | Quando | confidence |
|---|---|---|
exact | Il titolo coincide con la ricerca. | 1,0 per il primo risultato di questo tipo, 0,9 per i successivi |
alias | Corrisponde un altro nome, oppure le iniziali del titolo («mlk»). | 0,8; 0,7 per un primo risultato che non contiene alcuna parola della ricerca; 0,6 per una ricerca traslitterata |
misspelling | La ricerca ha corretto il testo inserito (did_you_mean). | 0,5 × la frazione del testo inserito conservata dalla correzione |
partial | Alcune parole cercate compaiono nel titolo, oppure solo nel testo. | 0,2 + 0,5 × la frazione delle parole cercate presente nel titolo; 0,2 se compaiono solo nel testo |
fulltext | Nessun titolo o altro nome corrisponde, quindi la ricerca è stata eseguita nel testo delle voci (BM25): una descrizione permette di trovare la voce di cui non si conosce il nome. | almeno 0,2 |
none | Nessuna corrispondenza. La risposta è vuota. | 0 |
Il grado di confidenza segue una regola fissa, non è una probabilità calibrata; una risposta il cui miglior risultato ha un punteggio inferiore a 0,2 viene restituita vuota. Ogni risultato contiene highlight, la frase della sua sintesi che contiene il maggior numero di parole cercate. Una ricerca senza risultati viene ripetuta una volta in caratteri latini (cirillico, greco, kana e hangul traslitterati, numeri dei toni del pinyin rimossi, vocali doppie del rōmaji abbreviate), e la risposta la indica come searched_as. I caratteri cinesi non vengono traslitterati.
| Opzione | Funzione |
|---|---|
first=true | Solo la corrispondenza migliore, oppure nessuna. |
topic={id}, geo={id} | Solo le voci che discendono da quell’argomento o nodo geografico; geo filtra tutte le corrispondenze fino a 1.000, e scope indica fin dove si estende la risposta. |
sort=central | Prima i soggetti con più link in entrata, fra tutte le corrispondenze fino a 1.000. |
max_grade={grade} | Solo le voci con un livello di lettura pari o inferiore a quello indicato. |
facets=1 | Conteggio delle corrispondenze per argomento di primo livello e per regione geografica, su tutte le corrispondenze fino a 1.000 (facets.counted). |
Ogni risposta
fields=a,b mantiene solo quelle chiavi di ciascun risultato (o della risposta, quando non contiene risultati); l’involucro (total, page, next, license) resta. Una risposta 200 memorizzabile nella cache contiene un ETag: invialo di nuovo come If-None-Match e, se la risposta non è cambiata, riceverai un 304 senza corpo. Last-Modified è la data di pubblicazione del corpus e ha solo valore informativo. Edgepedia-Corpus-Version indica la versione pubblicata del corpus e Content-Digest è lo SHA-256 del corpo (RFC 9530); anche il .md di una voce li include entrambi.
Altri endpoint
| Endpoint | Restituisce |
|---|---|
/api/v1/articles?after={id}&limit={1..1000} | Tutte le voci di General, percorse in un ordine fisso: {id, slug, title, api_url} e next (null alla fine). after= vuoto parte dall’inizio, e il percorso può riprendere dopo qualsiasi id, anche rimosso. |
/api/v1/trees, /api/v1/trees/topic, /api/v1/trees/geo | L’albero degli argomenti e l’albero geografico completi: nodes: [[id, label, parent index, own articles]]; un id che inizia con un punto prosegue l’id del nodo superiore. |
/api/v1/releases | Le versioni pubblicate del corpus, dalla più recente, e current. |
/api/v1/health | application/health+json: pass, warn o fail (503). |
/api/v1/manifest | Un reindirizzamento a un unico file JSONL compresso con gzip, una riga per voce: { id, slug, title, updated, sha256, topic } (sha256 del .md della voce). Scaricalo una volta per creare una copia speculare di Edgepedia. La somma di controllo si riferisce al testo pubblicato, prima delle correzioni dei lettori: una voce modificata dopo la pubblicazione in seguito a una segnalazione di un lettore non corrisponderà alla somma di controllo fino alla versione successiva. |
/api/v1/changes?since={release} | I file delle modifiche da quella versione a quella attuale, in ordine (il flusso inizia dalla 1.5: since=1.5 è la prima disponibile); ogni riga è { op, id, … }, con op uguale a uno fra added, changed, moved (from_slug è il vecchio indirizzo) o removed. |
/api/v1/events/{slug} | Le frasi di una voce che riportano una data: { date, precision, text, para }, date come YYYY, YYYY-MM o YYYY-MM-DD (negativo prima dell’era comune: -0044-03-15). Le date a.C. seguono la convenzione storica, non la numerazione astronomica degli anni: -0044 è il 44 a.C. (un normale parser ISO 8601 lo leggerebbe come 45 a.C.). La frase è la prova: leggila prima di considerare la data un fatto accertato. |
/api/v1/aliases/{id} | Gli altri nomi di una voce, comprese le sigle riportate nelle voci («NASA»); gli errori di ortografia e le varianti di maiuscole e minuscole sono esclusi, e fra due grafie dello stesso nome viene mantenuta quella senza punti («WHO», non «W.H.O.»). |
Risoluzione, annotazione e riconciliazione
Testo libero in entrata, id delle voci in uscita, senza modelli né embedding. Il testo inviato ad annotate, classify e geoparse non viene mai registrato né conservato.
| Endpoint | Restituisce |
|---|---|
/api/v1/resolve?name=Mercury&context=planet | La voce a cui più probabilmente si riferisce un nome: result, confidence, ambiguous, match (exact, alias, anchor, partial o none) e alternatives. type= mantiene i candidati che discendono da un unico id di argomento (quando nessuna delle prime 30 corrispondenze del nome vi si trova, la richiesta per un singolo nome esamina le 60 successive); limit= da 1 a 10. POST ne accetta fino a 50: { "names": ["Paris", "Koala"] } o { "queries": [{ "name": "Mercury", "context": "planet" }] }. Un nome che da solo non permette di individuare una voce risponde con ambiguous: true e l’ipotesi migliore in result; passa context per scegliere. |
/api/v1/surface?form=mercury | Tutte le voci a cui i link interni del corpus rimandavano con questa esatta espressione, con il numero di link e la quota di ciascuna (commonness). |
/api/v1/suggest?prefix=koa | Prima la voce con il titolo esatto, poi quella per cui corrisponde esattamente un altro nome, quindi i titoli che iniziano con il prefisso e infine gli altri nomi che iniziano allo stesso modo (matched riporta quel nome), per caselle di ricerca e interfacce vocali. |
POST /api/v1/annotate | { "text": "…" } (al massimo 20.000 caratteri): ogni espressione collegata con le sue posizioni (start, end, in unità di codice UTF-16, come JavaScript indicizza le stringhe: in Python, un carattere esterno al piano multilingue di base, come un’emoji, conta come due), la voce e il grado di confidenza. ?format=html restituisce anche il testo, con i caratteri speciali HTML convertiti in entità e ogni espressione trasformata in link. |
POST /api/v1/classify | { "text": "…" }: gli argomenti trattati dal testo, con punteggi calcolati in base ai percorsi nell’albero degli argomenti delle voci menzionate, e le quote degli argomenti di primo livello. |
POST /api/v1/geoparse | { "text": "…" }: i luoghi e i periodi nominati, nell’albero geografico (nodes, regions, places, periods); il ramo non geografico dell’albero (geo.nongeo) non è mai un luogo. |
/api/v1/mentions?term=CRISPR | Le voci che menzionano un soggetto senza rimandare alla sua voce con un link; complete: false indica che l’elenco delle voci che contengono un link alla sua voce è stato troncato. |
/api/v1/reconcile | Un endpoint Reconciliation Service API 0.2: il manifesto, queries in batch (GET o POST), suggerimenti di entità, tipi e proprietà, un’anteprima ed estensione dei dati (title, url, excerpt, topic, topic_path, importance_rank). JSONP con callback=. In OpenRefine: Reconcile › Start reconciling › Add standard service, poi incolla https://www.edgepedia.org/api/v1/reconcile. |
Il grafo dei link, le date e gli elenchi
I diagrammi (format=mermaid) sono testo Mermaid destinato a un sistema che lo visualizzi.
| Endpoint | Restituisce |
|---|---|
/api/v1/links/{slug} | I link della voce ad altre voci, nell’ordine di lettura, ciascuno con il proprio testo di ancoraggio e la frase che lo contiene. |
/api/v1/backlinks/{slug}?page= | Le voci che rimandano a essa, 30 per pagina, dalle più importanti, con il relativo testo di ancoraggio. |
/api/v1/path?from=&to= | La catena di link più breve fra due voci (al massimo 6 passaggi, evitando dove possibile i nodi molto connessi), con la frase che determina ogni passaggio. Il server MCP la chiama connect. |
/api/v1/compare?a=&b= | Due voci affiancate: paragrafi introduttivi, percorsi nell’albero degli argomenti, l’argomento più specifico che condividono, la catena che le collega, i link condivisi e quelli propri di ciascuna, e le rispettive tabelle Dati essenziali. |
/api/v1/graph/{slug}?depth=1|2&limit= | Fino a limit delle voci vicine più importanti (valore predefinito: 50, massimo: 200), e tutti i link fra esse. complete: false (qui, nei link in entrata e in rank/top) indica che il limite di tempo dell’endpoint, di circa un secondo, ha troncato la risposta; una risposta di questo tipo viene conservata nella cache per un solo minuto. |
POST /api/v1/context | { "ids": [...] }, fino a 50 id o indirizzi (accettati anche da /rank?ids= e /leads?ids=): i link fra le voci, le voci collegate alla maggior parte di esse, l’argomento e il luogo più specifici che condividono e il paragrafo introduttivo di ciascuna. |
/api/v1/rank?ids=, /api/v1/rank/top?topic=&limit= | L’importanza secondo PageRank: la somma di pr sull’intero corpus è 1, e la posizione 1 indica la voce più centrale. Attenzione ai nomi: importance in /search e nelle voci esprime questa posizione come percentile da 0 a 1; importance di /resolve è il valore grezzo di pr, mentre quello di /leads è { pr, rank }. |
/api/v1/timeline?topic=|geo=&from=&to= | Frasi con date tratte dalle voci di un argomento o di un luogo, dalla più antica, 50 per pagina; gli anni a.C. sono negativi. Un nodo conserva al massimo 200 eventi distribuiti sulle sue date, e from e to filtrano quel campione; una risposta tratta da un campione che ha raggiunto il limite riporta sampled: true e il relativo cap, e il suo total conta gli elementi del campione. |
/api/v1/onthisday?date=MM-DD, /api/v1/year/{year} | Eventi di un giorno dell’anno (per impostazione predefinita, oggi in UTC), oppure di un anno (da -9999 a 2100). Un giorno contiene al massimo 500 eventi e un anno 2.000; quando il limite è raggiunto, viene indicato sampled: true. |
/api/v1/featured?date=, /api/v1/featured.xml | La voce in evidenza del giorno (il Fatto del giorno della pagina iniziale) e un feed Atom degli ultimi dieci giorni. |
/api/v1/list?topic=|geo=&period=&type=person | Le voci di un argomento, oppure di un luogo e periodo (TBC, T500, T1000, T1800, T1946, T2001, T2021, NODATE), 30 per pagina; type=person mantiene le persone. Le righe di un elenco geografico contengono geo ma non id (per ottenerlo, recupera la voce). |
/api/v1/keyterms?topic=|geo=&limit= | Titoli e altri nomi di un sottoalbero, per predisporre un sistema di riconoscimento vocale. |
/api/v1/stats?topic=|geo=&by=period | Solo conteggi: voci, link e altri nomi per il corpus oppure per un nodo e i suoi nodi figli. Qui articles conta le voci distinte; in /geo e /trees/geo conta le collocazioni, quindi una voce presente in due periodi di una regione viene contata due volte. |
Individuazione e altri protocolli
- Scheda del server MCP: /.well-known/mcp/server-card.json (anche
/mcp/server-card): nome, endpoint, strumenti e versioni, senza collegarsi. Configurazione del registro:/.well-known/mcp/config-schema.jsone/.well-known/mcp/examples.json. - Catalogo IA: /.well-known/ai-catalog.json: tutte le modalità di accesso (MCP, questa API, A2A, NLWeb e Agent Skill), con esempi di query.
- Catalogo API: /.well-known/api-catalog, un insieme di link conforme alla RFC 9727 che indica questa API, la sua descrizione e questa documentazione.
- Agent Skill: /.well-known/agent-skills/index.json elenca
SKILL.mdcon la relativa impronta sha256. - OpenSearch: /opensearch.xml aggiunge Edgepedia come motore di ricerca.
- A2A:
https://www.edgepedia.org/a2a(JSON-RPC; A2A 1.0SendMessagee 0.3message/send; scheda in/.well-known/agent-card.json). Il nome di un soggetto restituisce le prime cinque voci; l’indirizzo di una voce restituisce la voce in Markdown con la sua riga di attribuzione. La risposta è sempre un messaggio, mai un task, e gli stessi metodi ricevono risposta anche su/mcp. - NLWeb:
https://www.edgepedia.org/ask?query=Mount%20Fuji(GET, oppure POST con un corpo JSON o con dati di un modulo) risponde nel formato a elenco di NLWeb, con unschema_objectdi schema.org per ogni risultato;streaming=trueinvia l’elenco come eventi inviati dal server. Non viene chiamato alcun modello. - Formati di una voce destinati alle macchine: l’indirizzo della voce restituisce il formato indicato da un’intestazione
Accept:text/markdown(con una stima dix-markdown-tokens),application/json(la risposta di questa API) oapplication/ld+json; per qualsiasi altro valore restituisce la pagina. Le pagine delle voci includono un’intestazioneLinkche indica questi formati, la licenza, il catalogo API e la descrizione OpenAPI.
File generati
Generati a partire da /openapi.json, così da restare sempre allineati.
| File | Che cos’è |
|---|---|
| /openapi-3.0.json | La stessa descrizione in OpenAPI 3.0.3, per gli strumenti che non leggono la versione 3.1. |
| /arazzo.json | Un flusso di lavoro Arazzo 1.0: ricerca, recupero della corrispondenza migliore, poi delle voci correlate. |
| /tools.json | Ogni endpoint JSON come funzione che un modello può chiamare, nei formati OpenAI, Anthropic e Gemini, e come JSON Schema con il relativo endpoint. |
| /edgepedia.d.ts | Tipi TypeScript per ogni risposta e per i parametri di ogni endpoint. |
| /edgepedia.postman_collection.json, /edgepedia.bruno.json, /edgepedia.insomnia.json, /edgepedia.http | Una richiesta di esempio per ogni endpoint, per Postman, Bruno, Insomnia e VS Code o JetBrains. |
Invia un User-Agent che indichi il nome del tuo programma, come fanno le raccolte (edgepedia-collection/1).